@rynx-ai/skills 0.1.10 → 0.1.11-beta.10

package/dist/artifact.d.ts

@@ -25,6 +25,8 @@ export interface SkillReceipt {
 }
 /** Receipt file written next to a skill at install time. */
 export declare const SKILL_RECEIPT_FILE = ".rynx-skill.json";
+/** A skill name is also used as a filesystem entry by provider adapters. */
+export declare const SAFE_SKILL_NAME: RegExp;
 /** The raw YAML frontmatter block of a `SKILL.md` (between the leading `---`s), or null. */
 export declare function extractSkillFrontmatter(content: string): string | null;
 /** Parse a `SKILL.md` body's leading YAML frontmatter for name + description. */

package/dist/artifact.js

@@ -11,6 +11,8 @@ import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 /** Receipt file written next to a skill at install time. */
 export const SKILL_RECEIPT_FILE = ".rynx-skill.json";
+/** A skill name is also used as a filesystem entry by provider adapters. */
+export const SAFE_SKILL_NAME = /^[a-z0-9][a-z0-9-]{0,127}$/;
 /** The raw YAML frontmatter block of a `SKILL.md` (between the leading `---`s), or null. */
 export function extractSkillFrontmatter(content) {
     const match = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/);
@@ -69,6 +71,8 @@ export async function readSkillMeta(skillDir) {
     const fm = parseSkillFrontmatter(content);
     if (!fm)
         return null;
+    if (!SAFE_SKILL_NAME.test(fm.name) || fm.name !== path.basename(skillDir))
+        return null;
     const ref = await readReceiptRef(skillDir);
     return { ...fm, dir: skillDir, ...(ref ? { ref } : {}) };
 }
@@ -104,7 +108,7 @@ export function parseSkillRefValue(value) {
     if (typeof value !== "object" || value === null)
         return null;
     const v = value;
-    if (typeof v.name !== "string" || !v.name.trim())
+    if (typeof v.name !== "string" || !SAFE_SKILL_NAME.test(v.name))
         return null;
     const install = v.install;
     if (typeof install !== "object" || install === null)

package/dist/index.d.ts

@@ -13,3 +13,4 @@
  */
 export * from "./artifact.js";
 export * from "./install.js";
+export * from "./local-discovery.js";

package/dist/index.js

@@ -13,3 +13,4 @@
  */
 export * from "./artifact.js";
 export * from "./install.js";
+export * from "./local-discovery.js";

package/dist/local-discovery-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/local-discovery-worker.js

@@ -0,0 +1,16 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { executeLocalSkillWorkerRequest } from "./local-discovery.js";
+if (!parentPort)
+    throw new Error("Local Skill worker requires a parent port");
+try {
+    parentPort.postMessage({
+        ok: true,
+        value: executeLocalSkillWorkerRequest(workerData, process.env),
+    });
+}
+catch (error) {
+    parentPort.postMessage({
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+    });
+}

package/dist/local-discovery.d.ts

@@ -0,0 +1,54 @@
+export type LocalSkillRuntime = "codex" | "traex" | "claude";
+export type LocalSkillRootKind = "provider" | "universal";
+export interface LocalSkillCandidate {
+    key: string;
+    name: string;
+    description: string;
+    runtime: LocalSkillRuntime;
+    sourcePath: string;
+    root: LocalSkillRootKind;
+    fileCount: number;
+    sizeBytes: number;
+}
+export interface LocalSkillBundleFile {
+    path: string;
+    contentBase64: string;
+    sizeBytes: number;
+    sha256: string;
+}
+export interface LocalSkillBundle {
+    name: string;
+    description: string;
+    sourcePath: string;
+    contentHash: string;
+    files: LocalSkillBundleFile[];
+}
+export interface LocalSkillBundleFailure {
+    key: string;
+    name: string;
+    sourcePath?: string;
+    message: string;
+}
+export interface LocalSkillBundleCollection {
+    bundles: LocalSkillBundle[];
+    failures: LocalSkillBundleFailure[];
+}
+type WorkerRequest = {
+    kind: "scan";
+    runtime: LocalSkillRuntime;
+} | {
+    kind: "collect";
+    runtime: LocalSkillRuntime;
+    keys: string[];
+};
+/** Scan provider-specific and universal Skill roots on this machine. */
+export declare function scanLocalSkillCandidates(runtime: LocalSkillRuntime, env?: NodeJS.ProcessEnv): LocalSkillCandidate[];
+/** Revalidate opaque scan keys and collect complete immutable payloads. */
+export declare function collectLocalSkillBundles(runtime: LocalSkillRuntime, keys: string[], env?: NodeJS.ProcessEnv): LocalSkillBundleCollection;
+/** Collect all valid Skill bundles below an already trusted local directory
+ * (for example, a safely extracted ZIP staging directory). */
+export declare function collectSkillBundlesFromDirectory(root: string): LocalSkillBundleCollection;
+export declare function scanLocalSkillCandidatesInWorker(runtime: LocalSkillRuntime, env?: NodeJS.ProcessEnv): Promise<LocalSkillCandidate[]>;
+export declare function collectLocalSkillBundlesInWorker(runtime: LocalSkillRuntime, keys: string[], env?: NodeJS.ProcessEnv): Promise<LocalSkillBundleCollection>;
+export declare function executeLocalSkillWorkerRequest(request: WorkerRequest, env: NodeJS.ProcessEnv): LocalSkillCandidate[] | LocalSkillBundleCollection;
+export {};

package/dist/local-discovery.js

@@ -0,0 +1,417 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, readdirSync, statSync, } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Worker } from "node:worker_threads";
+import { parseSkillFrontmatter, SAFE_SKILL_NAME } from "./artifact.js";
+const MAX_SKILL_FILE_BYTES = 512 * 1024;
+const MAX_SKILL_BUNDLE_BYTES = 8 * 1024 * 1024;
+const MAX_SKILL_IMPORT_BYTES = 24 * 1024 * 1024;
+const MAX_SKILL_FILES = 300;
+const MAX_DISCOVERY_DEPTH = 4;
+const MAX_DISCOVERY_DIRS = 2_000;
+const IGNORED_DIRS = new Set([
+    ".git",
+    ".hg",
+    ".svn",
+    ".cache",
+    ".npm",
+    ".pnpm-store",
+    "__pycache__",
+    "node_modules",
+]);
+/** Scan provider-specific and universal Skill roots on this machine. */
+export function scanLocalSkillCandidates(runtime, env = process.env) {
+    const byName = new Map();
+    for (const root of localSkillRoots(runtime, env)) {
+        const resolved = readableDirectory(root.path);
+        if (!resolved)
+            continue;
+        for (const skillDir of discoverSkillDirs(resolved, 0)) {
+            const candidate = readCandidate(skillDir, runtime, root.root);
+            if (!candidate)
+                continue;
+            const current = byName.get(candidate.name);
+            if (!current || (current.root === "universal" && candidate.root === "provider")) {
+                byName.set(candidate.name, candidate);
+            }
+        }
+    }
+    return [...byName.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+/** Revalidate opaque scan keys and collect complete immutable payloads. */
+export function collectLocalSkillBundles(runtime, keys, env = process.env) {
+    const bundles = [];
+    const failures = [];
+    let totalBytes = 0;
+    for (const key of keys) {
+        let payload;
+        try {
+            payload = decodeCandidateKey(key);
+            if (payload.runtime !== runtime)
+                throw new Error("runtime mismatch");
+            if (!isAllowedCandidatePath(payload, env)) {
+                throw new Error("skill path is outside runtime skill roots");
+            }
+            const bundle = collectBundle(payload.path);
+            if (!bundle)
+                throw new Error("SKILL.md not found or invalid");
+            const bytes = bundle.files.reduce((sum, file) => sum + file.sizeBytes, 0);
+            if (totalBytes + bytes > MAX_SKILL_IMPORT_BYTES) {
+                throw new Error("selected skills exceed the local import limit");
+            }
+            totalBytes += bytes;
+            bundles.push(bundle);
+        }
+        catch (error) {
+            failures.push({
+                key,
+                name: payload?.path ? path.basename(payload.path) : "unknown",
+                ...(payload?.path ? { sourcePath: payload.path } : {}),
+                message: messageOf(error),
+            });
+        }
+    }
+    return { bundles, failures };
+}
+/** Collect all valid Skill bundles below an already trusted local directory
+ * (for example, a safely extracted ZIP staging directory). */
+export function collectSkillBundlesFromDirectory(root) {
+    const resolved = readableDirectory(root);
+    if (!resolved)
+        return { bundles: [], failures: [] };
+    const bundles = [];
+    const failures = [];
+    for (const skillDir of discoverSkillDirs(resolved, 0)) {
+        try {
+            const bundle = collectBundle(skillDir);
+            if (!bundle)
+                throw new Error("SKILL.md not found or invalid");
+            bundles.push(bundle);
+        }
+        catch (error) {
+            failures.push({
+                key: skillDir,
+                name: path.basename(skillDir),
+                sourcePath: skillDir,
+                message: messageOf(error),
+            });
+        }
+    }
+    return { bundles, failures };
+}
+export function scanLocalSkillCandidatesInWorker(runtime, env = process.env) {
+    return runWorker({ kind: "scan", runtime }, env);
+}
+export function collectLocalSkillBundlesInWorker(runtime, keys, env = process.env) {
+    return runWorker({ kind: "collect", runtime, keys }, env);
+}
+export function executeLocalSkillWorkerRequest(request, env) {
+    return request.kind === "scan"
+        ? scanLocalSkillCandidates(request.runtime, env)
+        : collectLocalSkillBundles(request.runtime, request.keys, env);
+}
+function readCandidate(skillDir, runtime, root) {
+    const metadata = readMetadata(skillDir);
+    if (!metadata)
+        return undefined;
+    const summary = summarizeFiles(skillDir);
+    return {
+        key: encodeCandidateKey({ runtime, root, path: skillDir }),
+        ...metadata,
+        runtime,
+        sourcePath: skillDir,
+        root,
+        ...summary,
+    };
+}
+function readMetadata(skillDir) {
+    try {
+        const parsed = parseSkillFrontmatter(readFileSync(path.join(skillDir, "SKILL.md"), "utf8"));
+        if (!parsed || !SAFE_SKILL_NAME.test(parsed.name))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function summarizeFiles(skillDir) {
+    let fileCount = 0;
+    let sizeBytes = 0;
+    walkFiles(skillDir, skillDir, (absolute) => {
+        if (fileCount >= MAX_SKILL_FILES)
+            return false;
+        try {
+            const info = statSync(absolute);
+            fileCount += 1;
+            sizeBytes += info.size;
+        }
+        catch {
+            // Descriptive scan metadata is best effort.
+        }
+        return fileCount < MAX_SKILL_FILES;
+    });
+    return { fileCount, sizeBytes };
+}
+function collectBundle(skillDir) {
+    const metadata = readMetadata(skillDir);
+    if (!metadata)
+        return undefined;
+    const files = [];
+    let storedBytes = 0;
+    walkFiles(skillDir, skillDir, (absolute, relative) => {
+        if (files.length >= MAX_SKILL_FILES)
+            return false;
+        const info = statSync(absolute);
+        if (info.size > MAX_SKILL_FILE_BYTES) {
+            throw new Error(`skill file is too large: ${relative}`);
+        }
+        if (storedBytes + info.size > MAX_SKILL_BUNDLE_BYTES) {
+            throw new Error("skill bundle is too large");
+        }
+        const buffer = readFileSync(absolute);
+        if (buffer.byteLength > MAX_SKILL_FILE_BYTES) {
+            throw new Error(`skill file is too large: ${relative}`);
+        }
+        if (storedBytes + buffer.byteLength > MAX_SKILL_BUNDLE_BYTES) {
+            throw new Error("skill bundle is too large");
+        }
+        storedBytes += buffer.byteLength;
+        files.push({
+            path: relative,
+            contentBase64: buffer.toString("base64"),
+            sizeBytes: buffer.byteLength,
+            sha256: createHash("sha256").update(buffer).digest("hex"),
+        });
+        return true;
+    });
+    if (!files.some((file) => file.path === "SKILL.md"))
+        return undefined;
+    files.sort((left, right) => left.path.localeCompare(right.path));
+    return {
+        ...metadata,
+        sourcePath: skillDir,
+        contentHash: contentHash(files),
+        files,
+    };
+}
+function contentHash(files) {
+    const digest = createHash("sha256");
+    for (const file of files) {
+        digest.update(file.path);
+        digest.update("\0");
+        digest.update(file.sha256);
+        digest.update("\0");
+        digest.update(String(file.sizeBytes));
+        digest.update("\0");
+    }
+    return digest.digest("hex");
+}
+function localSkillRoots(runtime, env) {
+    const home = env.HOME?.trim() || homedir();
+    const universal = firstEnv(env, "AGENTS_SKILLS_DIR")
+        ?? path.join(firstEnv(env, "AGENTS_HOME") ?? path.join(home, ".agents"), "skills");
+    const provider = runtime === "codex"
+        ? [path.join(firstEnv(env, "CODEX_HOME") ?? path.join(home, ".codex"), "skills")]
+        : runtime === "claude"
+            ? [path.join(firstEnv(env, "CLAUDE_CONFIG_DIR", "CLAUDE_HOME") ?? path.join(home, ".claude"), "skills")]
+            : [
+                path.join(firstEnv(env, "TRAECLI_HOME") ?? path.join(home, ".traecli"), "skills"),
+                path.join(firstEnv(env, "TRAE_HOME", "TRAEX_HOME") ?? path.join(home, ".trae"), "skills"),
+            ];
+    return dedupeRoots([
+        ...provider.map((rootPath) => ({ root: "provider", path: rootPath })),
+        { root: "universal", path: universal },
+    ]);
+}
+function dedupeRoots(roots) {
+    const seen = new Set();
+    return roots.filter((root) => {
+        const key = path.resolve(root.path);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function discoverSkillDirs(root, depth, visited = new Set(), state = { count: 0 }) {
+    if (depth > MAX_DISCOVERY_DEPTH || state.count >= MAX_DISCOVERY_DIRS)
+        return [];
+    let resolved;
+    try {
+        if (!statSync(root).isDirectory())
+            return [];
+        resolved = realpathSync(root);
+    }
+    catch {
+        return [];
+    }
+    if (visited.has(resolved))
+        return [];
+    visited.add(resolved);
+    state.count += 1;
+    if (existsSync(path.join(resolved, "SKILL.md")))
+        return [resolved];
+    if (depth >= MAX_DISCOVERY_DEPTH)
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(resolved, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.isDirectory() || entry.isSymbolicLink() || shouldSkip(entry.name))
+            continue;
+        found.push(...discoverSkillDirs(path.join(resolved, entry.name), depth + 1, visited, state));
+        if (state.count >= MAX_DISCOVERY_DIRS)
+            break;
+    }
+    return found;
+}
+function walkFiles(root, current, visit) {
+    let realRoot = root;
+    let realCurrent = current;
+    if (root === current) {
+        try {
+            realRoot = realpathSync(root);
+            realCurrent = realRoot;
+        }
+        catch {
+            return true;
+        }
+    }
+    let entries;
+    try {
+        entries = readdirSync(realCurrent, { withFileTypes: true });
+    }
+    catch {
+        return true;
+    }
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        if (entry.isSymbolicLink() || shouldSkip(entry.name))
+            continue;
+        const absolute = path.join(realCurrent, entry.name);
+        if (entry.isDirectory()) {
+            if (!walkFiles(realRoot, absolute, visit))
+                return false;
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const relative = normalizeRelative(path.relative(realRoot, absolute));
+        if (relative && visit(absolute, relative) === false)
+            return false;
+    }
+    return true;
+}
+function shouldSkip(name) {
+    return !name || name.startsWith(".") || IGNORED_DIRS.has(name);
+}
+function normalizeRelative(value) {
+    const parts = value.replace(/\\/g, "/").split("/");
+    if (parts.some((part) => !part || part === "." || part === "..")) {
+        throw new Error("invalid skill file path");
+    }
+    return parts.join("/");
+}
+function encodeCandidateKey(payload) {
+    return Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+}
+function decodeCandidateKey(key) {
+    const bytes = Buffer.from(key, "base64url");
+    if (bytes.byteLength > 16 * 1024)
+        throw new Error("candidate key is too large");
+    const value = JSON.parse(bytes.toString("utf8"));
+    if (!isRuntime(value.runtime))
+        throw new Error("unsupported runtime");
+    if (value.root !== "provider" && value.root !== "universal")
+        throw new Error("unsupported root");
+    if (typeof value.path !== "string" || !value.path.trim())
+        throw new Error("missing path");
+    return { runtime: value.runtime, root: value.root, path: path.resolve(value.path) };
+}
+function isAllowedCandidatePath(payload, env) {
+    return localSkillRoots(payload.runtime, env)
+        .filter((root) => root.root === payload.root)
+        .some((root) => {
+        const allowed = readableDirectory(root.path);
+        if (!allowed)
+            return false;
+        try {
+            const candidate = realpathSync(payload.path);
+            const relative = path.relative(allowed, candidate);
+            return relative === "" || (relative !== ".." &&
+                !relative.startsWith(`..${path.sep}`) &&
+                !path.isAbsolute(relative));
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function readableDirectory(value) {
+    try {
+        const resolved = realpathSync(path.resolve(value));
+        return statSync(resolved).isDirectory() ? resolved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function firstEnv(env, ...keys) {
+    for (const key of keys) {
+        const value = env[key]?.trim();
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+function isRuntime(value) {
+    return value === "codex" || value === "traex" || value === "claude";
+}
+function runWorker(request, env) {
+    const workerUrl = new URL("./local-discovery-worker.js", import.meta.url);
+    // Source-mode test runners resolve the TypeScript barrel directly and do not
+    // emit the sibling worker. Production package builds always take the Worker
+    // path; source-mode keeps identical validation semantics synchronously.
+    if (!existsSync(fileURLToPath(workerUrl))) {
+        return Promise.resolve(executeLocalSkillWorkerRequest(request, env));
+    }
+    return new Promise((resolve, reject) => {
+        const worker = new Worker(workerUrl, {
+            workerData: request,
+            env,
+        });
+        worker.unref();
+        let settled = false;
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            void worker.terminate();
+            if (error)
+                reject(error);
+            else
+                resolve(value);
+        };
+        worker.once("message", (message) => {
+            if (!message?.ok)
+                finish(new Error(message?.error || "local Skill worker failed"));
+            else
+                finish(undefined, message.value);
+        });
+        worker.once("error", (error) => finish(error instanceof Error ? error : new Error(String(error))));
+        worker.once("exit", (code) => {
+            if (!settled)
+                finish(new Error(`local Skill worker exited without a result (${code})`));
+        });
+    });
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rynx-ai/skills",
-  "version": "0.1.10",
+  "version": "0.1.11-beta.10",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rynx-ai/rynx.git",
@@ -26,7 +26,7 @@
     }
   },
   "dependencies": {
-    "@rynx-ai/protocol": "0.1.10"
+    "@rynx-ai/protocol": "0.1.11-beta.10"
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json"