rulesync 13.0.0 → 14.0.0

package/dist/cli/index.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_import = require("../import-nbmxtKYi.cjs");
+const require_import = require("../import-Dh9PCQKq.cjs");
 let commander = require("commander");
 let zod_mini = require("zod/mini");
 let node_path = require("node:path");
@@ -14,6 +14,7 @@ let es_toolkit_promise = require("es-toolkit/promise");
 let _octokit_request_error = require("@octokit/request-error");
 let _octokit_rest = require("@octokit/rest");
 let node_child_process = require("node:child_process");
+let node_zlib = require("node:zlib");
 let fastmcp = require("fastmcp");
 let node_fs = require("node:fs");
 node_fs = require_import.__toESM(node_fs, 1);
@@ -1242,6 +1243,7 @@ const DERIVED_PATHS_NOT_GITIGNORED = /* @__PURE__ */ new Set([
 	"**/.grok/config.toml",
 	"**/.vibe/config.toml",
 	"**/reasonix.toml",
+	"**/.vscode/settings.json",
 	"**/.zed/settings.json",
 	"**/kilo.json",
 	"**/kilo.jsonc",
@@ -3548,6 +3550,516 @@ async function walkDirectory(dir, outputRoot, depth = 0, ctx = {
 	}
 	return results;
 }
+const DEFAULT_NPM_TOKEN_ENV = "NPM_TOKEN";
+/** Abbreviated packument media type (install metadata only). */
+const PACKUMENT_ACCEPT_HEADER = "application/vnd.npm.install-v1+json";
+/** Timeout for registry HTTP requests (60 seconds). */
+const NPM_FETCH_TIMEOUT_MS = 6e4;
+/** Maximum accepted tarball size (compressed), aligned with the extraction cap. */
+const MAX_TARBALL_SIZE = 100 * 1024 * 1024;
+/**
+* npm package name rules (scoped or unscoped, URL-safe characters only).
+* This also guards against URL path injection into registry requests.
+*/
+const NPM_PACKAGE_NAME_REGEX = /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/i;
+const MAX_NPM_PACKAGE_NAME_LENGTH = 214;
+const INTEGRITY_ALGORITHM_PREFERENCE = [
+	"sha512",
+	"sha384",
+	"sha256",
+	"sha1"
+];
+var NpmClientError = class extends Error {
+	statusCode;
+	constructor(message, options) {
+		super(message, { cause: options?.cause });
+		this.name = "NpmClientError";
+		this.statusCode = options?.statusCode;
+	}
+};
+function validateNpmPackageName(name) {
+	if (name.length > MAX_NPM_PACKAGE_NAME_LENGTH || !NPM_PACKAGE_NAME_REGEX.test(name)) throw new NpmClientError(`Invalid npm package name: "${name}". Expected "name" or "@scope/name".`);
+}
+function validateNpmRegistryUrl(url, options) {
+	const ctrl = require_import.findControlCharacter(url);
+	if (ctrl) throw new NpmClientError(`Registry URL contains control character ${ctrl.hex} at position ${ctrl.position}`);
+	if (!url.startsWith("https://") && !url.startsWith("http://")) throw new NpmClientError(`Unsupported registry URL: "${url}". Use https:// (or http://).`);
+	if (url.startsWith("http://")) options?.logger?.warn(`Registry URL "${url}" uses an unencrypted protocol. Consider using https:// instead.`);
+}
+/**
+* Resolve the registry token from the environment. When `tokenEnv` is set it
+* must name an existing environment variable; otherwise `NPM_TOKEN` is used
+* when present. The token value itself is never logged.
+*/
+function resolveNpmToken(params) {
+	const { tokenEnv } = params;
+	if (tokenEnv !== void 0) {
+		const value = process.env[tokenEnv];
+		if (value === void 0 || value === "") throw new NpmClientError(`Environment variable "${tokenEnv}" (from tokenEnv) is not set. Export it or remove the tokenEnv field.`);
+		return value;
+	}
+	const fallback = process.env[DEFAULT_NPM_TOKEN_ENV];
+	return fallback === void 0 || fallback === "" ? void 0 : fallback;
+}
+/** Build the packument URL for a (possibly scoped) package on a registry. */
+function buildPackumentUrl(params) {
+	const { registryUrl, packageName } = params;
+	validateNpmPackageName(packageName);
+	const base = registryUrl.endsWith("/") ? registryUrl : `${registryUrl}/`;
+	const encodedName = packageName.replaceAll("/", "%2F");
+	return new URL(encodedName, base).toString();
+}
+async function fetchWithTimeout(url, headers) {
+	try {
+		return await fetch(url, {
+			headers,
+			redirect: "follow",
+			signal: AbortSignal.timeout(NPM_FETCH_TIMEOUT_MS)
+		});
+	} catch (error) {
+		throw new NpmClientError(`Network error while requesting ${url}`, { cause: error });
+	}
+}
+/**
+* Fetch the (abbreviated) packument for a package from a registry.
+*/
+async function fetchPackument(params) {
+	const { registryUrl, packageName, token } = params;
+	validateNpmPackageName(packageName);
+	const url = buildPackumentUrl({
+		registryUrl,
+		packageName
+	});
+	const headers = { Accept: PACKUMENT_ACCEPT_HEADER };
+	if (token) headers.Authorization = `Bearer ${token}`;
+	const response = await fetchWithTimeout(url, headers);
+	if (!response.ok) throw new NpmClientError(`Failed to fetch package metadata for "${packageName}" from ${registryUrl}: HTTP ${response.status}`, { statusCode: response.status });
+	try {
+		return await response.json();
+	} catch (error) {
+		throw new NpmClientError(`Failed to parse package metadata for "${packageName}" from ${registryUrl}`, { cause: error });
+	}
+}
+/**
+* Resolve a requested version or dist-tag against a packument. Only exact
+* versions and dist-tags are supported — semver ranges are intentionally out
+* of scope (no semver dependency).
+*/
+function resolvePackumentVersion(params) {
+	const { packument, packageName, requested } = params;
+	const versions = packument.versions ?? {};
+	if (Object.prototype.hasOwnProperty.call(versions, requested)) return requested;
+	const distTags = packument["dist-tags"] ?? {};
+	const tagged = Object.prototype.hasOwnProperty.call(distTags, requested) ? distTags[requested] : void 0;
+	if (tagged !== void 0 && Object.prototype.hasOwnProperty.call(versions, tagged)) return tagged;
+	throw new NpmClientError(`Could not resolve "${packageName}@${requested}": not an exact published version or dist-tag. Note: semver ranges are not supported by the npm transport.`);
+}
+/** Get the dist metadata (tarball URL, integrity) for a resolved version. */
+function getPackumentVersionDist(params) {
+	const { packument, packageName, version } = params;
+	const versions = packument.versions ?? {};
+	const dist = (Object.prototype.hasOwnProperty.call(versions, version) ? versions[version] : void 0)?.dist;
+	if (!dist?.tarball) throw new NpmClientError(`Registry metadata for "${packageName}@${version}" is missing the dist.tarball URL.`);
+	return dist;
+}
+/**
+* Download a package tarball. The Authorization header is only attached when
+* the tarball is hosted on the same origin (scheme + host) as the registry,
+* so the token never leaks to third-party CDNs or plaintext downgrades.
+*/
+async function fetchTarball(params) {
+	const { tarballUrl, registryUrl, token } = params;
+	const maxSize = params.maxSize ?? MAX_TARBALL_SIZE;
+	if (!tarballUrl.startsWith("https://") && !tarballUrl.startsWith("http://")) throw new NpmClientError(`Unsupported tarball URL: "${tarballUrl}". Use https:// (or http://).`);
+	const headers = {};
+	if (token && isSameOrigin(tarballUrl, registryUrl)) headers.Authorization = `Bearer ${token}`;
+	const response = await fetchWithTimeout(tarballUrl, headers);
+	if (!response.ok) throw new NpmClientError(`Failed to download tarball ${tarballUrl}: HTTP ${response.status}`, { statusCode: response.status });
+	const contentLength = Number.parseInt(response.headers.get("content-length") ?? "", 10);
+	if (Number.isFinite(contentLength) && contentLength > maxSize) throw new NpmClientError(oversizedTarballMessage(tarballUrl, maxSize));
+	return await readBodyWithLimit({
+		response,
+		tarballUrl,
+		maxSize
+	});
+}
+function oversizedTarballMessage(tarballUrl, maxSize) {
+	return `Tarball ${tarballUrl} exceeds max size of ${maxSize / 1024 / 1024}MB.`;
+}
+/**
+* Read a response body incrementally, aborting as soon as the size cap is
+* exceeded. content-length can be absent or forged, so the streaming check is
+* the actual enforcement of the cap.
+*/
+async function readBodyWithLimit(params) {
+	const { response, tarballUrl, maxSize } = params;
+	const reader = response.body?.getReader();
+	if (!reader) {
+		const arrayBuffer = await response.arrayBuffer();
+		if (arrayBuffer.byteLength > maxSize) throw new NpmClientError(oversizedTarballMessage(tarballUrl, maxSize));
+		return Buffer.from(arrayBuffer);
+	}
+	const chunks = [];
+	let totalBytes = 0;
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		totalBytes += value.byteLength;
+		if (totalBytes > maxSize) {
+			await reader.cancel();
+			throw new NpmClientError(oversizedTarballMessage(tarballUrl, maxSize));
+		}
+		chunks.push(Buffer.from(value));
+	}
+	return Buffer.concat(chunks);
+}
+function isSameOrigin(urlA, urlB) {
+	try {
+		return new URL(urlA).origin === new URL(urlB).origin;
+	} catch {
+		return false;
+	}
+}
+/**
+* Convert a hex sha1 shasum to the SRI form used by `verifyTarballIntegrity`.
+* Rejects malformed shasum values so a broken value is never recorded in the
+* lockfile as a seemingly valid SRI string.
+*/
+function shasumToSri(shasum) {
+	if (!/^[0-9a-f]{40}$/i.test(shasum)) throw new NpmClientError(`Malformed sha1 shasum in registry metadata: "${shasum}"`);
+	return `sha1-${Buffer.from(shasum, "hex").toString("base64")}`;
+}
+/**
+* Verify a downloaded tarball against registry integrity metadata.
+* Prefers the strongest supported algorithm in the SRI `integrity` string and
+* falls back to the legacy sha1 `shasum`. An `integrity` string that is
+* present but cannot be parsed fails closed; a warning is only logged when
+* the registry provides no integrity metadata at all.
+*/
+function verifyTarballIntegrity(params) {
+	const { tarball, integrity, shasum, context, logger } = params;
+	if (integrity !== void 0) {
+		const sri = pickStrongestSriEntry(integrity);
+		if (!sri) throw new NpmClientError(`Unsupported or malformed integrity metadata for ${context}. Expected an SRI string with sha512/sha384/sha256/sha1.`);
+		const actual = (0, node_crypto.createHash)(sri.algorithm).update(tarball).digest("base64");
+		if (actual !== sri.digest) throw new NpmClientError(`Integrity verification failed for ${context}: expected ${sri.algorithm}-${sri.digest}, got ${sri.algorithm}-${actual}. The tarball may have been tampered with.`);
+		return;
+	}
+	if (shasum) {
+		const actual = (0, node_crypto.createHash)("sha1").update(tarball).digest("hex");
+		if (actual !== shasum.toLowerCase()) throw new NpmClientError(`Integrity verification failed for ${context}: expected sha1 ${shasum}, got ${actual}. The tarball may have been tampered with.`);
+		return;
+	}
+	logger?.warn(`No integrity metadata available for ${context}; skipping tarball verification.`);
+}
+function pickStrongestSriEntry(integrity) {
+	if (!integrity) return;
+	const entries = integrity.split(/\s+/).map((entry) => {
+		const separatorIndex = entry.indexOf("-");
+		if (separatorIndex === -1) return void 0;
+		const algorithm = entry.slice(0, separatorIndex);
+		const digest = entry.slice(separatorIndex + 1).split("?")[0] ?? "";
+		const known = INTEGRITY_ALGORITHM_PREFERENCE.find((a) => a === algorithm);
+		if (!known || digest.length === 0) return void 0;
+		return {
+			algorithm: known,
+			digest
+		};
+	}).filter((entry) => Boolean(entry));
+	for (const algorithm of INTEGRITY_ALGORITHM_PREFERENCE) {
+		const match = entries.find((entry) => entry.algorithm === algorithm);
+		if (match) return match;
+	}
+}
+/**
+* Log contextual hints for NpmClientError to help users troubleshoot
+* authentication problems without ever logging the token itself.
+*/
+function logNpmAuthHints(params) {
+	const { error, logger } = params;
+	if (error.statusCode === 401 || error.statusCode === 403) logger.info("Hint: The registry rejected the request. Set NPM_TOKEN (or the per-source tokenEnv variable) to a token with read access. Note: .npmrc files are not read by the npm transport.");
+	else if (error.statusCode === 404) logger.info("Hint: Package not found. Check the package name and the registry URL. Some registries also return 404 for unauthorized requests.");
+}
+const NpmLockedSkillSchema = zod_mini.z.object({ integrity: zod_mini.z.string() });
+/**
+* Schema for a single locked npm source entry.
+*/
+const NpmLockedSourceSchema = zod_mini.z.object({
+	registry: (0, zod_mini.optional)(zod_mini.z.string()),
+	requestedVersion: (0, zod_mini.optional)(zod_mini.z.string()),
+	resolvedVersion: zod_mini.z.string(),
+	/** SRI integrity of the package tarball as reported by the registry. */
+	integrity: (0, zod_mini.optional)(zod_mini.z.string()),
+	resolvedAt: (0, zod_mini.optional)(zod_mini.z.string()),
+	skills: zod_mini.z.record(zod_mini.z.string(), NpmLockedSkillSchema)
+});
+const NpmSourcesLockSchema = zod_mini.z.object({
+	lockfileVersion: zod_mini.z.number(),
+	sources: zod_mini.z.record(zod_mini.z.string(), NpmLockedSourceSchema)
+});
+/**
+* Create an empty npm lockfile structure.
+*/
+function createEmptyNpmLock() {
+	return {
+		lockfileVersion: 1,
+		sources: {}
+	};
+}
+/**
+* Read the npm lockfile from disk.
+* @returns The parsed lockfile, or an empty lockfile if it doesn't exist or is invalid.
+*/
+async function readNpmLockFile(params) {
+	const { logger } = params;
+	const lockPath = (0, node_path.join)(params.projectRoot, require_import.RULESYNC_NPM_SOURCES_LOCK_RELATIVE_FILE_PATH);
+	if (!await require_import.fileExists(lockPath)) {
+		logger.debug("No npm sources lockfile found, starting fresh.");
+		return createEmptyNpmLock();
+	}
+	try {
+		const content = await require_import.readFileContent(lockPath);
+		const result = NpmSourcesLockSchema.safeParse(JSON.parse(content));
+		if (result.success) return result.data;
+		logger.warn(`Invalid npm sources lockfile format (${require_import.RULESYNC_NPM_SOURCES_LOCK_RELATIVE_FILE_PATH}). Starting fresh.`);
+		return createEmptyNpmLock();
+	} catch {
+		logger.warn(`Failed to read npm sources lockfile (${require_import.RULESYNC_NPM_SOURCES_LOCK_RELATIVE_FILE_PATH}). Starting fresh.`);
+		return createEmptyNpmLock();
+	}
+}
+/**
+* Write the npm lockfile to disk.
+*/
+async function writeNpmLockFile(params) {
+	const { logger } = params;
+	const lockPath = (0, node_path.join)(params.projectRoot, require_import.RULESYNC_NPM_SOURCES_LOCK_RELATIVE_FILE_PATH);
+	await require_import.writeFileContent(lockPath, JSON.stringify(params.lock, null, 2) + "\n");
+	logger.debug(`Wrote npm sources lockfile to ${lockPath}`);
+}
+/**
+* Normalize an npm source key (package name) for lockfile lookups.
+*/
+function normalizeNpmSourceKey(source) {
+	return source.trim();
+}
+/**
+* Get the locked entry for an npm source key, if it exists.
+*/
+function getNpmLockedSource(lock, sourceKey) {
+	const normalized = normalizeNpmSourceKey(sourceKey);
+	return Object.prototype.hasOwnProperty.call(lock.sources, normalized) ? lock.sources[normalized] : void 0;
+}
+/**
+* Set (or update) a locked entry for an npm source key (immutable).
+*/
+function setNpmLockedSource(lock, sourceKey, entry) {
+	return {
+		lockfileVersion: lock.lockfileVersion,
+		sources: {
+			...lock.sources,
+			[normalizeNpmSourceKey(sourceKey)]: entry
+		}
+	};
+}
+/**
+* Get the skill names from a locked npm source entry.
+*/
+function getNpmLockedSkillNames(entry) {
+	return Object.keys(entry.skills);
+}
+//#endregion
+//#region src/lib/npm-tar.ts
+/**
+* Minimal, hardened tar reader for npm package tarballs (EXPERIMENTAL npm
+* transport). Intentionally supports only the subset of the (pax-extended)
+* ustar format that npm-compatible registries produce:
+*
+* - regular files (typeflag "0" / "\0")
+* - directories (typeflag "5") — skipped; directories are created implicitly
+* - pax extended headers (typeflag "x") — only the `path` override is honored
+* - GNU long names (typeflag "L")
+*
+* Everything else (symlinks, hardlinks, devices, FIFOs, ...) is skipped and
+* never materialized. Extraction is bounded by file-count and total-byte caps
+* to prevent decompression bombs, and every entry path is validated against
+* traversal (absolute paths, `..` segments, backslashes).
+*/
+const BLOCK_SIZE = 512;
+var NpmTarError = class extends Error {
+	constructor(message, cause) {
+		super(message, { cause });
+		this.name = "NpmTarError";
+	}
+};
+/**
+* Gunzip and extract a npm package tarball into an in-memory file list.
+* Throws {@link NpmTarError} on malformed archives, traversal attempts, or
+* resource-limit violations.
+*/
+function extractPackageTarball(params) {
+	const { tarball, onSkippedEntry } = params;
+	const maxFiles = params.maxFiles ?? 1e4;
+	const maxTotalBytes = params.maxTotalBytes ?? 104857600;
+	let tar;
+	try {
+		tar = (0, node_zlib.gunzipSync)(tarball, { maxOutputLength: maxTotalBytes + maxFiles * 3 * BLOCK_SIZE + 2 * BLOCK_SIZE });
+	} catch (error) {
+		throw new NpmTarError("Failed to gunzip package tarball", error);
+	}
+	return parseTarBuffer({
+		tar,
+		maxFiles,
+		maxTotalBytes,
+		onSkippedEntry
+	});
+}
+function parseTarBuffer(params) {
+	const { tar, maxFiles, maxTotalBytes, onSkippedEntry } = params;
+	const files = [];
+	let totalBytes = 0;
+	let offset = 0;
+	let pendingLongName;
+	let pendingPaxPath;
+	while (offset + BLOCK_SIZE <= tar.length) {
+		const header = tar.subarray(offset, offset + BLOCK_SIZE);
+		if (isZeroBlock(header)) break;
+		verifyHeaderChecksum(header);
+		const size = parseOctalField(header, 124, 12, "size");
+		const typeflag = String.fromCharCode(header[156] ?? 0);
+		const dataStart = offset + BLOCK_SIZE;
+		const dataEnd = dataStart + size;
+		if (dataEnd > tar.length) throw new NpmTarError("Truncated tar archive: entry data extends past end of archive");
+		switch (typeflag) {
+			case "x": {
+				const records = parsePaxRecords(tar.subarray(dataStart, dataEnd));
+				if (records.has("size")) throw new NpmTarError("Unsupported tar archive: pax size override is not supported");
+				pendingPaxPath = records.get("path") ?? pendingPaxPath;
+				break;
+			}
+			case "L":
+				pendingLongName = trimAtFirstNul(tar.toString("utf8", dataStart, dataEnd));
+				break;
+			case "g": {
+				const records = parsePaxRecords(tar.subarray(dataStart, dataEnd));
+				if (records.has("size") || records.has("path")) throw new NpmTarError("Unsupported tar archive: global pax size/path overrides are not supported");
+				break;
+			}
+			case "0":
+			case "\0": {
+				const rawName = resolveEntryName({
+					header,
+					pendingLongName,
+					pendingPaxPath
+				});
+				pendingLongName = void 0;
+				pendingPaxPath = void 0;
+				const relativePath = toSafeRelativePath(rawName);
+				if (relativePath !== null) {
+					if (files.length + 1 > maxFiles) throw new NpmTarError(`Package tarball exceeds max file count of ${maxFiles}. Aborting to prevent resource exhaustion.`);
+					totalBytes += size;
+					if (totalBytes > maxTotalBytes) throw new NpmTarError(`Package tarball exceeds max total size of ${maxTotalBytes / 1024 / 1024}MB. Aborting to prevent resource exhaustion.`);
+					files.push({
+						relativePath,
+						content: Buffer.from(tar.subarray(dataStart, dataEnd))
+					});
+				}
+				break;
+			}
+			case "5":
+				pendingLongName = void 0;
+				pendingPaxPath = void 0;
+				break;
+			default: {
+				const rawName = resolveEntryName({
+					header,
+					pendingLongName,
+					pendingPaxPath
+				});
+				pendingLongName = void 0;
+				pendingPaxPath = void 0;
+				onSkippedEntry?.(`Skipping unsupported tar entry type "${typeflag}" for "${rawName}" (only regular files are extracted).`);
+				break;
+			}
+		}
+		offset = dataStart + Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE;
+	}
+	return files;
+}
+function isZeroBlock(block) {
+	return block.every((byte) => byte === 0);
+}
+/** Cut a string at its first NUL character (tar fields are NUL-terminated). */
+function trimAtFirstNul(value) {
+	const nulIndex = value.indexOf("\0");
+	return nulIndex === -1 ? value : value.substring(0, nulIndex);
+}
+function parseOctalField(block, offset, length, field) {
+	if (((block[offset] ?? 0) & 128) !== 0) throw new NpmTarError(`Unsupported tar archive: base-256 ${field} field is not supported`);
+	const text = trimAtFirstNul(block.toString("latin1", offset, offset + length)).trim();
+	if (text === "") return 0;
+	if (!/^[0-7]+$/.test(text)) throw new NpmTarError(`Invalid tar header: malformed octal ${field} field`);
+	return Number.parseInt(text, 8);
+}
+/**
+* Verify the ustar header checksum: the unsigned byte sum of the 512-byte
+* header with the checksum field itself treated as ASCII spaces.
+*/
+function verifyHeaderChecksum(header) {
+	const stored = parseOctalField(header, 148, 8, "checksum");
+	let sum = 0;
+	for (let i = 0; i < BLOCK_SIZE; i++) sum += i >= 148 && i < 156 ? 32 : header[i] ?? 0;
+	if (sum !== stored) throw new NpmTarError("Invalid tar header: checksum mismatch");
+}
+function readCString(block, offset, length) {
+	const end = block.indexOf(0, offset);
+	const stop = end === -1 || end > offset + length ? offset + length : end;
+	return block.toString("utf8", offset, stop);
+}
+function resolveEntryName(params) {
+	const { header, pendingLongName, pendingPaxPath } = params;
+	if (pendingPaxPath !== void 0) return pendingPaxPath;
+	if (pendingLongName !== void 0) return pendingLongName;
+	const name = readCString(header, 0, 100);
+	const prefix = header.toString("latin1", 257, 262) === "ustar" ? readCString(header, 345, 155) : "";
+	return prefix.length > 0 ? `${prefix}/${name}` : name;
+}
+/**
+* Parse pax extended header records of the form `<len> <key>=<value>\n`,
+* where `<len>` is the decimal length of the whole record.
+*/
+function parsePaxRecords(data) {
+	const records = /* @__PURE__ */ new Map();
+	let offset = 0;
+	while (offset < data.length) {
+		if (data[offset] === 0) break;
+		const spaceIndex = data.indexOf(32, offset);
+		if (spaceIndex === -1) throw new NpmTarError("Invalid pax header: missing length delimiter");
+		const recordLength = Number.parseInt(data.toString("utf8", offset, spaceIndex), 10);
+		if (!Number.isInteger(recordLength) || recordLength <= 0 || offset + recordLength > data.length) throw new NpmTarError("Invalid pax header: malformed record length");
+		const record = data.toString("utf8", spaceIndex + 1, offset + recordLength - 1);
+		const equalsIndex = record.indexOf("=");
+		if (equalsIndex !== -1) records.set(record.slice(0, equalsIndex), record.slice(equalsIndex + 1));
+		offset += recordLength;
+	}
+	return records;
+}
+/**
+* Validate a tar entry path and convert it to a package-root-relative path
+* with the first component stripped. Returns null for entries that resolve to
+* the package root itself (e.g. the `package/` folder entry). Throws on
+* traversal attempts.
+*/
+function toSafeRelativePath(rawPath) {
+	if (rawPath.includes("\0")) throw new NpmTarError(`Unsafe tar entry path (NUL byte): "${rawPath}"`);
+	if (rawPath.includes("\\")) throw new NpmTarError(`Unsafe tar entry path (backslash): "${rawPath}"`);
+	if (rawPath.startsWith("/")) throw new NpmTarError(`Unsafe tar entry path (absolute): "${rawPath}"`);
+	const segments = rawPath.split("/").filter((segment) => segment !== "" && segment !== ".");
+	if (segments.includes("..")) throw new NpmTarError(`Unsafe tar entry path (".." segment): "${rawPath}"`);
+	segments.shift();
+	if (segments.length === 0) return null;
+	return segments.join("/");
+}
 /**
 * Schema for a single locked skill entry with content integrity.
 */
@@ -3737,37 +4249,41 @@ async function resolveAndFetchSources(params) {
 		projectRoot,
 		logger
 	});
+	let npmLock = options.updateSources ? createEmptyNpmLock() : await readNpmLockFile({
+		projectRoot,
+		logger
+	});
 	if (options.frozen) assertFrozenLockCoversSources({
 		lock,
+		npmLock,
 		sources
 	});
 	const originalLockJson = JSON.stringify(lock);
+	const originalNpmLockJson = JSON.stringify(npmLock);
 	const client = new GitHubClient({ token: GitHubClient.resolveToken(options.token) });
 	const localSkillNames = await require_import.getLocalSkillDirNames(projectRoot);
 	let totalSkillCount = 0;
 	const allFetchedSkillNames = /* @__PURE__ */ new Set();
 	for (const sourceEntry of sources) try {
-		const { skillCount, fetchedSkillNames, updatedLock } = await fetchSourceByTransport({
+		const result = await fetchSingleSource({
 			sourceEntry,
 			client,
 			projectRoot,
 			lock,
+			npmLock,
 			localSkillNames,
 			alreadyFetchedSkillNames: allFetchedSkillNames,
 			updateSources: options.updateSources ?? false,
 			frozen: options.frozen ?? false,
 			logger
 		});
-		lock = updatedLock;
-		totalSkillCount += skillCount;
-		for (const name of fetchedSkillNames) allFetchedSkillNames.add(name);
+		lock = result.lock;
+		npmLock = result.npmLock;
+		totalSkillCount += result.skillCount;
+		for (const name of result.fetchedSkillNames) allFetchedSkillNames.add(name);
 	} catch (error) {
-		logger.error(`Failed to fetch source "${sourceEntry.source}": ${require_import.formatError(error)}`);
-		if (error instanceof GitHubClientError) logGitHubAuthHints({
-			error,
-			logger
-		});
-		else if (error instanceof GitClientError) logGitClientHints({
+		logSourceFetchFailure({
+			sourceEntry,
 			error,
 			logger
 		});
@@ -3777,18 +4293,100 @@ async function resolveAndFetchSources(params) {
 		sources,
 		logger
 	});
-	if (!options.frozen && JSON.stringify(lock) !== originalLockJson) await writeLockFile({
+	npmLock = pruneStaleNpmLockEntries({
+		npmLock,
+		sources,
+		logger
+	});
+	await writeLockFilesIfChanged({
 		projectRoot,
 		lock,
+		npmLock,
+		originalLockJson,
+		originalNpmLockJson,
+		frozen: options.frozen ?? false,
 		logger
 	});
-	else logger.debug("Lockfile unchanged, skipping write.");
 	return {
 		fetchedSkillCount: totalSkillCount,
 		sourcesProcessed: sources.length
 	};
 }
 /**
+* Dispatch a single source to the npm fetcher or the git/github fetcher,
+* returning the (possibly) updated lock objects for both lockfiles.
+*/
+async function fetchSingleSource(params) {
+	const { sourceEntry, lock, npmLock } = params;
+	if ((sourceEntry.transport ?? "github") === "npm") {
+		const result = await fetchSourceViaNpm({
+			sourceEntry,
+			projectRoot: params.projectRoot,
+			npmLock,
+			localSkillNames: params.localSkillNames,
+			alreadyFetchedSkillNames: params.alreadyFetchedSkillNames,
+			updateSources: params.updateSources,
+			logger: params.logger
+		});
+		return {
+			skillCount: result.skillCount,
+			fetchedSkillNames: result.fetchedSkillNames,
+			lock,
+			npmLock: result.updatedLock
+		};
+	}
+	const result = await fetchSourceByTransport({
+		sourceEntry,
+		client: params.client,
+		projectRoot: params.projectRoot,
+		lock,
+		localSkillNames: params.localSkillNames,
+		alreadyFetchedSkillNames: params.alreadyFetchedSkillNames,
+		updateSources: params.updateSources,
+		frozen: params.frozen,
+		logger: params.logger
+	});
+	return {
+		skillCount: result.skillCount,
+		fetchedSkillNames: result.fetchedSkillNames,
+		lock: result.updatedLock,
+		npmLock
+	};
+}
+/** Log a per-source fetch failure with transport-specific troubleshooting hints. */
+function logSourceFetchFailure(params) {
+	const { sourceEntry, error, logger } = params;
+	logger.error(`Failed to fetch source "${sourceEntry.source}": ${require_import.formatError(error)}`);
+	if (error instanceof GitHubClientError) logGitHubAuthHints({
+		error,
+		logger
+	});
+	else if (error instanceof GitClientError) logGitClientHints({
+		error,
+		logger
+	});
+	else if (error instanceof NpmClientError) logNpmAuthHints({
+		error,
+		logger
+	});
+}
+/** Write each lockfile only when it changed (and never in frozen mode). */
+async function writeLockFilesIfChanged(params) {
+	const { projectRoot, lock, npmLock, originalLockJson, originalNpmLockJson, frozen, logger } = params;
+	if (!frozen && JSON.stringify(lock) !== originalLockJson) await writeLockFile({
+		projectRoot,
+		lock,
+		logger
+	});
+	else logger.debug("Lockfile unchanged, skipping write.");
+	if (!frozen && JSON.stringify(npmLock) !== originalNpmLockJson) await writeNpmLockFile({
+		projectRoot,
+		lock: npmLock,
+		logger
+	});
+	else logger.debug("npm lockfile unchanged, skipping write.");
+}
+/**
 * Log contextual hints for GitClientError to help users troubleshoot.
 */
 function logGitClientHints(params) {
@@ -3797,13 +4395,15 @@ function logGitClientHints(params) {
 	else logger.info("Hint: Check your git credentials (SSH keys, credential helper, or access token).");
 }
 /**
-* Frozen mode: validate the lockfile covers every declared source. Throws with
-* remediation guidance listing any uncovered source keys.
+* Frozen mode: validate the lockfiles cover every declared source. Throws with
+* remediation guidance listing any uncovered source keys. npm-transport
+* sources are checked against the npm lockfile; everything else against the
+* main sources lockfile.
 */
 function assertFrozenLockCoversSources(params) {
-	const { lock, sources } = params;
+	const { lock, npmLock, sources } = params;
 	const missingKeys = [];
-	for (const source of sources) if (!getLockedSource(lock, source.source)) missingKeys.push(source.source);
+	for (const source of sources) if (!((source.transport ?? "github") === "npm" ? getNpmLockedSource(npmLock, source.source) : getLockedSource(lock, source.source))) missingKeys.push(source.source);
 	if (missingKeys.length > 0) throw new Error(`Frozen install failed: lockfile is missing entries for: ${missingKeys.join(", ")}. Run 'rulesync install' to update the lockfile.`);
 }
 /**
@@ -3839,7 +4439,7 @@ async function fetchSourceByTransport(params) {
 */
 function pruneStaleLockEntries(params) {
 	const { lock, sources, logger } = params;
-	const sourceKeys = new Set(sources.map((s) => normalizeSourceKey(s.source)));
+	const sourceKeys = new Set(sources.filter((s) => (s.transport ?? "github") !== "npm").map((s) => normalizeSourceKey(s.source)));
 	const prunedSources = {};
 	for (const [key, value] of Object.entries(lock.sources)) if (sourceKeys.has(normalizeSourceKey(key))) prunedSources[key] = value;
 	else logger.debug(`Pruned stale lockfile entry: ${key}`);
@@ -3849,6 +4449,21 @@ function pruneStaleLockEntries(params) {
 	};
 }
 /**
+* Prune stale npm lockfile entries whose keys are not in the current
+* npm-transport sources (immutable — returns a fresh lock object).
+*/
+function pruneStaleNpmLockEntries(params) {
+	const { npmLock, sources, logger } = params;
+	const sourceKeys = new Set(sources.filter((s) => (s.transport ?? "github") === "npm").map((s) => normalizeNpmSourceKey(s.source)));
+	const prunedSources = {};
+	for (const [key, value] of Object.entries(npmLock.sources)) if (sourceKeys.has(normalizeNpmSourceKey(key))) prunedSources[key] = value;
+	else logger.debug(`Pruned stale npm lockfile entry: ${key}`);
+	return {
+		lockfileVersion: npmLock.lockfileVersion,
+		sources: prunedSources
+	};
+}
+/**
 * Check if all locked skills exist on disk in the curated directory.
 */
 async function checkLockedSkillsExist(curatedDir, skillNames) {
@@ -3916,16 +4531,31 @@ async function writeSkillAndComputeIntegrity(params) {
 	return { integrity };
 }
 /**
+* Merge back locked skills that still exist in the remote but were skipped
+* during fetching (due to local precedence, already-fetched, etc.). Skills no
+* longer present in the remote (e.g. renamed or deleted upstream) are
+* intentionally dropped. Shared by the git/github and npm lock updates.
+*/
+function mergeFetchedWithLockedSkills(params) {
+	const { fetchedSkills, lockedSkills, remoteSkillNames } = params;
+	const remoteSet = new Set(remoteSkillNames);
+	const mergedSkills = { ...fetchedSkills };
+	if (lockedSkills) {
+		for (const [skillName, skillEntry] of Object.entries(lockedSkills)) if (!(skillName in mergedSkills) && remoteSet.has(skillName)) mergedSkills[skillName] = skillEntry;
+	}
+	return mergedSkills;
+}
+/**
 * Merge newly fetched skills with existing locked skills and update the lockfile.
 */
 function buildLockUpdate(params) {
 	const { lock, sourceKey, fetchedSkills, locked, requestedRef, resolvedSha, remoteSkillNames, logger } = params;
 	const fetchedNames = Object.keys(fetchedSkills);
-	const remoteSet = new Set(remoteSkillNames);
-	const mergedSkills = { ...fetchedSkills };
-	if (locked) {
-		for (const [skillName, skillEntry] of Object.entries(locked.skills)) if (!(skillName in mergedSkills) && remoteSet.has(skillName)) mergedSkills[skillName] = skillEntry;
-	}
+	const mergedSkills = mergeFetchedWithLockedSkills({
+		fetchedSkills,
+		lockedSkills: locked?.skills,
+		remoteSkillNames
+	});
 	const updatedLock = setLockedSource(lock, sourceKey, {
 		requestedRef,
 		resolvedRef: resolvedSha,
@@ -4366,6 +4996,265 @@ async function fetchSourceViaGit(params) {
 		updatedLock: result.updatedLock
 	};
 }
+/**
+* Select the skill files inside an extracted npm package, mirroring the git
+* transport's discovery: files under `skills/` (or the configured `path`) are
+* grouped per subdirectory; a package whose `SKILL.md` sits at the package
+* root is installed as a single skill (root fallback via
+* {@link shouldUseRootFallback}), named after the requested skill or, for
+* wildcard fetches, after the package's base name.
+*/
+function selectNpmSkillFiles(params) {
+	const { allFiles, skillsPath, skillFilter, isWildcard, packageName } = params;
+	const normalizedBase = node_path.posix.normalize(skillsPath.replace(/\\/g, "/")).replace(/\/+$/, "");
+	if (normalizedBase === "" || normalizedBase === ".") return {
+		remoteFiles: allFiles,
+		skillFilter,
+		isWildcard
+	};
+	const prefix = `${normalizedBase}/`;
+	const filesUnderBase = allFiles.filter((file) => file.relativePath.startsWith(prefix)).map((file) => ({
+		relativePath: file.relativePath.substring(prefix.length),
+		content: file.content
+	}));
+	if (filesUnderBase.length > 0) return {
+		remoteFiles: filesUnderBase,
+		skillFilter,
+		isWildcard
+	};
+	const hasRootSkillFile = allFiles.some((file) => file.relativePath === require_import.SKILL_FILE_NAME);
+	const fallbackFilter = isWildcard ? [npmPackageBaseName(packageName)] : skillFilter;
+	const [singleSkillName] = fallbackFilter;
+	if (fallbackFilter.length === 1 && singleSkillName !== void 0 && shouldUseRootFallback({
+		skillFilter: fallbackFilter,
+		isWildcard: false,
+		hasRootSkillFile,
+		hasRequestedSkillDir: false
+	})) return {
+		remoteFiles: allFiles,
+		skillFilter: fallbackFilter,
+		isWildcard: false
+	};
+	return {
+		remoteFiles: filesUnderBase,
+		skillFilter,
+		isWildcard
+	};
+}
+/** Base name of an npm package: `@scope/name` -> `name`. */
+function npmPackageBaseName(packageName) {
+	const slashIndex = packageName.indexOf("/");
+	return slashIndex === -1 ? packageName : packageName.substring(slashIndex + 1);
+}
+/**
+* Resolve the version to fetch for an npm source: the locked version when
+* available (deterministic re-fetch), otherwise the declared `ref` (exact
+* version or dist-tag, defaulting to "latest") resolved via the packument.
+*/
+function resolveNpmFetchVersion(params) {
+	const { sourceEntry, locked, updateSources } = params;
+	if (locked && !updateSources) return {
+		lockedVersion: locked.resolvedVersion,
+		requestedVersion: locked.requestedVersion
+	};
+	return {
+		lockedVersion: void 0,
+		requestedVersion: sourceEntry.ref ?? "latest"
+	};
+}
+/**
+* Resolve the package version via the registry packument, download the
+* tarball, and verify it against the registry (and, when re-fetching a locked
+* version, the locked) integrity metadata.
+*/
+async function downloadVerifiedNpmTarball(params) {
+	const { packageName, registryUrl, token, lockedVersion, requestedVersion, locked, logger } = params;
+	const packument = await fetchPackument({
+		registryUrl,
+		packageName,
+		token
+	});
+	const resolvedVersion = lockedVersion ?? resolvePackumentVersion({
+		packument,
+		packageName,
+		requested: requestedVersion ?? "latest"
+	});
+	logger.debug(`Resolved ${packageName}@${requestedVersion ?? "latest"} to ${resolvedVersion}`);
+	const dist = getPackumentVersionDist({
+		packument,
+		packageName,
+		version: resolvedVersion
+	});
+	const tarball = await fetchTarball({
+		tarballUrl: dist.tarball,
+		registryUrl,
+		token
+	});
+	const context = `${packageName}@${resolvedVersion}`;
+	verifyTarballIntegrity({
+		tarball,
+		integrity: dist.integrity,
+		shasum: dist.shasum,
+		context,
+		logger
+	});
+	if (locked?.integrity && locked.resolvedVersion === resolvedVersion) verifyTarballIntegrity({
+		tarball,
+		integrity: locked.integrity,
+		context,
+		logger
+	});
+	return {
+		resolvedVersion,
+		dist,
+		tarball
+	};
+}
+/**
+* Extract a verified npm tarball in memory and convert its entries into
+* remote skill files, skipping any file above MAX_FILE_SIZE.
+*/
+function extractNpmRemoteFiles(params) {
+	const { tarball, logger } = params;
+	const extracted = extractPackageTarball({
+		tarball,
+		onSkippedEntry: (message) => logger.warn(message)
+	});
+	const allFiles = [];
+	for (const entry of extracted) {
+		if (entry.content.length > 10485760) {
+			logger.warn(`Skipping file "${entry.relativePath}" (${(entry.content.length / 1024 / 1024).toFixed(2)}MB exceeds ${require_import.MAX_FILE_SIZE / 1024 / 1024}MB limit).`);
+			continue;
+		}
+		allFiles.push({
+			relativePath: entry.relativePath,
+			content: entry.content.toString("utf8")
+		});
+	}
+	return allFiles;
+}
+/** Build the npm lockfile entry for a fetched source. */
+function buildNpmLockEntry(params) {
+	const { sourceEntry, requestedVersion, resolvedVersion, dist, mergedSkills } = params;
+	const integrity = dist.integrity ?? (dist.shasum !== void 0 ? shasumToSri(dist.shasum) : void 0);
+	return {
+		...sourceEntry.registry !== void 0 && { registry: sourceEntry.registry },
+		...requestedVersion !== void 0 && { requestedVersion },
+		resolvedVersion,
+		...integrity !== void 0 && { integrity },
+		resolvedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		skills: mergedSkills
+	};
+}
+/**
+* Fetch skills from a single npm-transport source (EXPERIMENTAL): resolve the
+* package version via the registry packument, download and verify the
+* tarball, extract it in-memory with the hardened tar reader, and install the
+* discovered skills into the curated directory.
+*/
+async function fetchSourceViaNpm(params) {
+	const { sourceEntry, projectRoot, npmLock, localSkillNames, alreadyFetchedSkillNames, updateSources, logger } = params;
+	const packageName = sourceEntry.source;
+	validateNpmPackageName(packageName);
+	const registryUrl = sourceEntry.registry ?? "https://registry.npmjs.org";
+	validateNpmRegistryUrl(registryUrl, { logger });
+	const token = resolveNpmToken({ tokenEnv: sourceEntry.tokenEnv });
+	const sourceKey = packageName;
+	const locked = getNpmLockedSource(npmLock, sourceKey);
+	const lockedSkillNames = locked ? getNpmLockedSkillNames(locked) : [];
+	const curatedDir = (0, node_path.join)(projectRoot, require_import.RULESYNC_CURATED_SKILLS_RELATIVE_DIR_PATH);
+	const { lockedVersion, requestedVersion } = resolveNpmFetchVersion({
+		sourceEntry,
+		locked,
+		updateSources
+	});
+	if (lockedVersion !== void 0) {
+		if (await checkLockedSkillsExist(curatedDir, lockedSkillNames)) {
+			logger.debug(`Version unchanged for ${sourceKey}, skipping re-fetch.`);
+			return {
+				skillCount: 0,
+				fetchedSkillNames: lockedSkillNames,
+				updatedLock: npmLock
+			};
+		}
+	}
+	const { resolvedVersion, dist, tarball } = await downloadVerifiedNpmTarball({
+		packageName,
+		registryUrl,
+		token,
+		lockedVersion,
+		requestedVersion,
+		locked,
+		logger
+	});
+	const allFiles = extractNpmRemoteFiles({
+		tarball,
+		logger
+	});
+	const declaredFilter = sourceEntry.skills ?? ["*"];
+	const declaredWildcard = declaredFilter.length === 1 && declaredFilter[0] === "*";
+	const { remoteFiles, skillFilter, isWildcard } = selectNpmSkillFiles({
+		allFiles,
+		skillsPath: sourceEntry.path ?? "skills",
+		skillFilter: declaredFilter,
+		isWildcard: declaredWildcard,
+		packageName
+	});
+	const skillFileMap = groupRemoteFilesBySkillRoot({
+		remoteFiles,
+		skillFilter,
+		isWildcard
+	});
+	const allNames = [...skillFileMap.keys()];
+	const filteredNames = isWildcard ? allNames : allNames.filter((n) => skillFilter.includes(n));
+	if (locked) await cleanPreviousCuratedSkills({
+		curatedDir,
+		lockedSkillNames,
+		logger
+	});
+	const lockedForIntegrityCheck = locked ? {
+		resolvedRef: locked.resolvedVersion,
+		skills: locked.skills
+	} : void 0;
+	const fetchedSkills = {};
+	for (const skillName of filteredNames) {
+		if (shouldSkipSkill({
+			skillName,
+			sourceKey,
+			localSkillNames,
+			alreadyFetchedSkillNames,
+			logger
+		})) continue;
+		fetchedSkills[skillName] = await writeSkillAndComputeIntegrity({
+			skillName,
+			files: skillFileMap.get(skillName) ?? [],
+			curatedDir,
+			locked: lockedForIntegrityCheck,
+			resolvedSha: resolvedVersion,
+			sourceKey,
+			logger
+		});
+		logger.debug(`Fetched skill "${skillName}" from ${sourceKey}`);
+	}
+	const fetchedNames = Object.keys(fetchedSkills);
+	const updatedLock = setNpmLockedSource(npmLock, sourceKey, buildNpmLockEntry({
+		sourceEntry,
+		requestedVersion,
+		resolvedVersion,
+		dist,
+		mergedSkills: mergeFetchedWithLockedSkills({
+			fetchedSkills,
+			lockedSkills: locked?.skills,
+			remoteSkillNames: filteredNames
+		})
+	}));
+	logger.info(`Fetched ${fetchedNames.length} skill(s) from ${sourceKey}: ${fetchedNames.join(", ") || "(none)"}`);
+	return {
+		skillCount: fetchedNames.length,
+		fetchedSkillNames: fetchedNames,
+		updatedLock
+	};
+}
 //#endregion
 //#region src/cli/commands/install.ts
 const INSTALL_MODES = [
@@ -6795,7 +7684,7 @@ function wrapCommand$1({ name, errorCode, handler, getVersion, loggerFactory = c
 }
 //#endregion
 //#region src/cli/index.ts
-const getVersion = () => "13.0.0";
+const getVersion = () => "14.0.0";
 function wrapCommand(name, errorCode, handler) {
 	return wrapCommand$1({
 		name,