@mhmdreza-rafiei/agentry 0.2.1 → 0.3.0

package/dist/cli.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { animateLogo, badge, delay, printHelp, sky, theme } from "./_chunks/theme2.mjs";
-import { execFileSync, execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import https from "node:https";
 import { createHash } from "node:crypto";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { dirname, join, resolve, sep } from "node:path";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { xdgCache, xdgConfig } from "xdg-basedir";
 import { parse, stringify } from "yaml";
 import { z } from "zod";
@@ -16,7 +16,7 @@ import { determineAgent } from "@vercel/detect-agent";
 import { stripVTControlCharacters } from "node:util";
 import { Writable } from "node:stream";
 var name = "@mhmdreza-rafiei/agentry";
-var version = "0.2.0";
+var version = "0.3.0";
 const ARTIFACT_KINDS = [
 	"skill",
 	"rule",
@@ -34,15 +34,21 @@ function isLocalPath(source) {
 		return false;
 	}
 }
+const SAFE_REF$1 = /^[a-zA-Z0-9][\w./-]*$/;
 function parseGithubTreeUrl(url) {
 	const m = url.match(/^https?:\/\/github\.com\/([\w.-]+\/[\w.-]+?)\/tree\/([^/]+)\/(.+)$/);
 	if (!m) return null;
+	const ref = m[2];
+	if (!SAFE_REF$1.test(ref)) throw new Error(`Invalid git ref in source URL: "${ref}"`);
 	return {
 		ownerRepo: m[1],
-		ref: m[2],
+		ref,
 		subpath: m[3].replace(/\/+$/, "")
 	};
 }
+function redactUrl(url) {
+	return url.replace(/:\/\/([^/@]+)@/g, "://***@");
+}
 function parseSource(source) {
 	if (!source || typeof source !== "string") throw new Error("Empty source.");
 	const raw = source;
@@ -140,7 +146,9 @@ function saveToCache(parsed, clonedRoot) {
 		cpSync(clonedRoot, dest, { recursive: true });
 	} catch {}
 }
+const SAFE_REF = /^[a-zA-Z0-9][\w./-]*$/;
 function cloneTo(url, dest, ref) {
+	if (ref && !SAFE_REF.test(ref)) throw new Error(`Invalid git ref: "${ref}"`);
 	execFileSync("git", [
 		"clone",
 		"--quiet",
@@ -158,28 +166,39 @@ function cloneTo(url, dest, ref) {
 		"pipe"
 	] });
 }
+function assertInsideRoot(root, candidate) {
+	const base = resolve(root);
+	const resolved = resolve(candidate);
+	const prefix = base.endsWith(sep) ? base : base + sep;
+	const a = resolved.toLowerCase();
+	const b = base.toLowerCase();
+	const p = prefix.toLowerCase();
+	if (a !== b && !a.startsWith(p)) throw new Error(`Path escapes source root: "${candidate}"`);
+	return resolved;
+}
 function withSubpath(root, subpath, cleanupRoot) {
+	const cleanup = () => rmSync(cleanupRoot, {
+		recursive: true,
+		force: true
+	});
 	if (!subpath) return {
 		root,
-		cleanup: () => rmSync(cleanupRoot, {
-			recursive: true,
-			force: true
-		})
+		cleanup
 	};
-	const sub = join(root, subpath);
+	let sub;
+	try {
+		sub = assertInsideRoot(root, join(root, subpath));
+	} catch (e) {
+		cleanup();
+		throw e;
+	}
 	if (!existsSync(sub)) {
-		rmSync(cleanupRoot, {
-			recursive: true,
-			force: true
-		});
+		cleanup();
 		throw new Error(`Subpath "${subpath}" not found.`);
 	}
 	return {
 		root: sub,
-		cleanup: () => rmSync(cleanupRoot, {
-			recursive: true,
-			force: true
-		})
+		cleanup
 	};
 }
 async function resolveSource(source, opts = {}) {
@@ -193,6 +212,7 @@ async function resolveSource(source, opts = {}) {
 	}
 	const url = parsed.url;
 	if (!url) throw new Error(`Cannot resolve source "${parsed.raw}".`);
+	const safeUrl = redactUrl(url);
 	const tmp = mkdtempSync(join(tmpdir(), "agentry-src-"));
 	try {
 		cloneTo(url, tmp, parsed.ref);
@@ -206,7 +226,7 @@ async function resolveSource(source, opts = {}) {
 		const cacheOk = existsSync(cached) && existsSync(join(cached, ".git"));
 		if (cacheOk && opts.confirmCache) {
 			if (await opts.confirmCache({
-				url,
+				url: safeUrl,
 				cacheDir: cached,
 				error: detail
 			})) {
@@ -218,12 +238,105 @@ async function resolveSource(source, opts = {}) {
 				};
 			}
 		}
-		throw new Error(`git clone failed for ${url}\n${detail}${cacheOk ? "\n(A local cache exists — re-run interactively to load it, or pass -y to auto-use cache.)" : ""}`);
+		throw new Error(`git clone failed for ${safeUrl}\n${detail}${cacheOk ? "\n(A local cache exists — re-run interactively to load it, or pass -y to auto-use cache.)" : ""}`);
 	}
 	saveToCache(parsed, tmp);
 	return withSubpath(tmp, parsed.subpath, tmp);
 }
+const DEFAULT_IGNORES = [
+	".git",
+	".github",
+	"node_modules",
+	".agents",
+	".agentry",
+	".cursor",
+	".claude",
+	".vscode",
+	"dist",
+	"build",
+	".DS_Store"
+];
+function parseIgnorePattern(pattern) {
+	const trimmed = pattern.trim();
+	if (!trimmed || trimmed.startsWith("#")) return null;
+	const isDirOnly = trimmed.endsWith("/");
+	let p = isDirOnly ? trimmed.slice(0, -1) : trimmed;
+	const isRootAnchored = p.startsWith("/");
+	if (isRootAnchored) p = p.slice(1);
+	let regexStr = "";
+	for (let i = 0; i < p.length; i++) {
+		const char = p[i];
+		if (char === "*") if (p[i + 1] === "*") {
+			regexStr += ".*";
+			i++;
+			if (p[i + 1] === "/") i++;
+		} else regexStr += "[^/]*";
+		else if (char === "?") regexStr += "[^/]";
+		else if ([
+			".",
+			"+",
+			"^",
+			"$",
+			"{",
+			"}",
+			"(",
+			")",
+			"|",
+			"[",
+			"]",
+			"\\"
+		].includes(char)) regexStr += "\\" + char;
+		else regexStr += char;
+	}
+	let regex;
+	if (isRootAnchored) regex = new RegExp(`^${regexStr}(/.*)?$`, "i");
+	else if (p.includes("/")) regex = new RegExp(`(^|/)${regexStr}(/.*)?$`, "i");
+	else regex = new RegExp(`(^|/)${regexStr}($|/)`, "i");
+	return {
+		raw: trimmed,
+		isDirOnly,
+		regex
+	};
+}
+function parseIgnoreFile(content) {
+	return content.split(/\r?\n/).map((line) => parseIgnorePattern(line)).filter((r) => r !== null);
+}
+function loadIgnoreRules(root) {
+	const candidates = [".agentryignore", ".agentry.ignore"];
+	const rules = [];
+	for (const name of candidates) {
+		const file = join(root, name);
+		if (existsSync(file)) try {
+			const text = readFileSync(file, "utf8");
+			rules.push(...parseIgnoreFile(text));
+		} catch {}
+	}
+	return rules;
+}
+function isDefaultIgnored(relPath) {
+	return relPath.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "").split("/").some((s) => DEFAULT_IGNORES.includes(s));
+}
+function createIgnoreMatcher(root) {
+	const fileRules = loadIgnoreRules(root);
+	return (relPath, isDirectory = false) => {
+		if (!relPath || relPath === "." || relPath === "./") return false;
+		const normalized = relPath.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+		if (!normalized) return false;
+		if (isDefaultIgnored(normalized)) return true;
+		for (const rule of fileRules) {
+			if (rule.isDirOnly && !isDirectory) {
+				if (rule.regex.test(normalized + "/")) return true;
+				continue;
+			}
+			if (rule.regex.test(normalized)) return true;
+		}
+		return false;
+	};
+}
 const SKILL_MARKER = "SKILL.md";
+const AGENT_MARKER = "AGENT.md";
+const RULE_MARKER = "RULE.md";
+const CURSORRULES_MARKER = ".cursorrules";
 const FILE_EXT = ".mdc";
 const PROFILE_EXTS = [".yaml", ".yml"];
 const KIND_DIRS = {
@@ -253,6 +366,12 @@ function firstHeading(md) {
 	const m = md.match(/^#\s+(.+)$/m);
 	return m ? m[1].trim() : "";
 }
+function frontmatterName(md) {
+	const fm = md.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!fm) return "";
+	const m = fm[1].match(/^name:\s*(.+)$/m);
+	return m ? m[1].trim().replace(/^['"]|['"]$/g, "") : "";
+}
 function frontmatterDescription(md) {
 	const fm = md.match(/^---\r?\n([\s\S]*?)\r?\n---/);
 	if (!fm) return "";
@@ -300,69 +419,178 @@ function makeArtifact(kind, category, name, srcPath, isFile) {
 		description: isFile ? readDescription(srcPath) : folderDescription(srcPath)
 	};
 }
-function collectSkills(base, out) {
+function rel(root, fullPath) {
+	return relative(root, fullPath).replace(/\\/g, "/");
+}
+function collectSkills(root, base, out, matcher) {
 	for (const child of entries(base)) {
 		if (!child.isDirectory()) continue;
 		const childDir = join(base, child.name);
+		if (matcher(rel(root, childDir), true)) continue;
 		if (existsSync(join(childDir, SKILL_MARKER))) out.push(makeArtifact("skill", null, child.name, childDir, false));
 		else for (const item of entries(childDir)) {
 			if (!item.isDirectory()) continue;
 			const itemDir = join(childDir, item.name);
+			if (matcher(rel(root, itemDir), true)) continue;
 			if (existsSync(join(itemDir, SKILL_MARKER))) out.push(makeArtifact("skill", child.name, item.name, itemDir, false));
 		}
 	}
 }
-function collectMdc(kind, base, out) {
-	for (const child of entries(base)) if (child.isFile() && child.name.endsWith(FILE_EXT)) out.push(makeArtifact(kind, null, child.name.slice(0, -4), join(base, child.name), true));
-	else if (child.isDirectory()) {
-		const subDir = join(base, child.name);
-		for (const item of entries(subDir)) if (item.isFile() && item.name.endsWith(FILE_EXT)) out.push(makeArtifact(kind, child.name, item.name.slice(0, -4), join(subDir, item.name), true));
+function collectMdc(root, kind, base, out, matcher) {
+	for (const child of entries(base)) {
+		const childPath = join(base, child.name);
+		if (child.isFile() && child.name.endsWith(FILE_EXT)) {
+			if (matcher(rel(root, childPath), false)) continue;
+			out.push(makeArtifact(kind, null, child.name.slice(0, -4), childPath, true));
+		} else if (child.isDirectory()) {
+			if (matcher(rel(root, childPath), true)) continue;
+			for (const item of entries(childPath)) {
+				const itemPath = join(childPath, item.name);
+				if (item.isFile() && item.name.endsWith(FILE_EXT)) {
+					if (matcher(rel(root, itemPath), false)) continue;
+					out.push(makeArtifact(kind, child.name, item.name.slice(0, -4), itemPath, true));
+				}
+			}
+		}
 	}
 }
-function collectProfiles(base, out) {
-	for (const child of entries(base)) if (child.isFile() && PROFILE_EXTS.some((e) => child.name.endsWith(e))) {
-		const stem = child.name.replace(/\.(yaml|yml)$/, "");
-		out.push(makeArtifact("profile", null, stem, join(base, child.name), true));
-	} else if (child.isDirectory()) {
-		const subDir = join(base, child.name);
-		for (const item of entries(subDir)) if (item.isFile() && PROFILE_EXTS.some((e) => item.name.endsWith(e))) {
-			const stem = item.name.replace(/\.(yaml|yml)$/, "");
-			out.push(makeArtifact("profile", child.name, stem, join(subDir, item.name), true));
+function collectProfiles(root, base, out, matcher) {
+	for (const child of entries(base)) {
+		const childPath = join(base, child.name);
+		if (child.isFile() && PROFILE_EXTS.some((e) => child.name.endsWith(e))) {
+			if (matcher(rel(root, childPath), false)) continue;
+			const stem = child.name.replace(/\.(yaml|yml)$/, "");
+			out.push(makeArtifact("profile", null, stem, childPath, true));
+		} else if (child.isDirectory()) {
+			if (matcher(rel(root, childPath), true)) continue;
+			for (const item of entries(childPath)) {
+				const itemPath = join(childPath, item.name);
+				if (item.isFile() && PROFILE_EXTS.some((e) => item.name.endsWith(e))) {
+					if (matcher(rel(root, itemPath), false)) continue;
+					const stem = item.name.replace(/\.(yaml|yml)$/, "");
+					out.push(makeArtifact("profile", child.name, stem, itemPath, true));
+				}
+			}
 		}
 	}
 }
-function collectScripts(base, out) {
+function collectScripts(root, base, out, matcher) {
 	for (const child of entries(base)) {
 		if (!child.isDirectory()) continue;
 		const childDir = join(base, child.name);
+		if (matcher(rel(root, childDir), true)) continue;
 		if (entries(childDir).some((e) => e.isFile())) out.push(makeArtifact("script", null, child.name, childDir, false));
-		else for (const item of entries(childDir)) if (item.isDirectory() && entries(join(childDir, item.name)).some((e) => e.isFile())) out.push(makeArtifact("script", child.name, item.name, join(childDir, item.name), false));
+		else for (const item of entries(childDir)) {
+			const itemDir = join(childDir, item.name);
+			if (!item.isDirectory() || matcher(rel(root, itemDir), true)) continue;
+			if (entries(itemDir).some((e) => e.isFile())) out.push(makeArtifact("script", child.name, item.name, join(childDir, item.name), false));
+		}
 	}
 }
-function collectRootSkills(root, out) {
+function collectRootSkills(root, out, matcher) {
+	const rootSkillFile = join(root, SKILL_MARKER);
+	if (existsSync(rootSkillFile) && !matcher(SKILL_MARKER, false)) {
+		let name = "";
+		try {
+			name = frontmatterName(readFileSync(rootSkillFile, "utf8"));
+		} catch {}
+		if (!name) name = basename(root) || "skill";
+		out.push(makeArtifact("skill", null, name, root, false));
+	}
 	for (const child of entries(root)) {
 		if (!child.isDirectory() || child.name.startsWith(".") || ROOT_SKIP.has(child.name)) continue;
 		const childDir = join(root, child.name);
+		if (matcher(child.name, true)) continue;
 		if (existsSync(join(childDir, SKILL_MARKER))) out.push(makeArtifact("skill", null, child.name, childDir, false));
-		else for (const item of entries(childDir)) if (item.isDirectory() && existsSync(join(childDir, item.name, SKILL_MARKER))) out.push(makeArtifact("skill", child.name, item.name, join(childDir, item.name), false));
+		else for (const item of entries(childDir)) {
+			if (!item.isDirectory()) continue;
+			const itemDir = join(childDir, item.name);
+			if (matcher(rel(root, itemDir), true)) continue;
+			if (existsSync(join(itemDir, SKILL_MARKER))) out.push(makeArtifact("skill", child.name, item.name, itemDir, false));
+		}
 	}
 }
-function collectRootMdc(kind, root, out) {
-	for (const child of entries(root)) if (child.isFile() && child.name.endsWith(FILE_EXT) && !child.name.startsWith(".")) out.push(makeArtifact(kind, null, child.name.slice(0, -4), join(root, child.name), true));
-	else if (child.isDirectory() && !child.name.startsWith(".") && !ROOT_SKIP.has(child.name)) {
-		const subDir = join(root, child.name);
-		for (const item of entries(subDir)) if (item.isFile() && item.name.endsWith(FILE_EXT)) out.push(makeArtifact(kind, child.name, item.name.slice(0, -4), join(subDir, item.name), true));
+function collectRootMdc(kind, root, out, matcher) {
+	if (kind === "agent") {
+		const rootAgent = join(root, AGENT_MARKER);
+		if (existsSync(rootAgent) && !matcher(AGENT_MARKER, false)) {
+			let name = "";
+			try {
+				name = frontmatterName(readFileSync(rootAgent, "utf8"));
+			} catch {}
+			out.push(makeArtifact("agent", null, name || "agent", rootAgent, true));
+		}
+	}
+	if (kind === "rule") {
+		const rootRule = join(root, RULE_MARKER);
+		if (existsSync(rootRule) && !matcher(RULE_MARKER, false)) {
+			let name = "";
+			try {
+				name = frontmatterName(readFileSync(rootRule, "utf8"));
+			} catch {}
+			out.push(makeArtifact("rule", null, name || "rule", rootRule, true));
+		}
+		const cursorRules = join(root, CURSORRULES_MARKER);
+		if (existsSync(cursorRules) && !matcher(CURSORRULES_MARKER, false)) out.push(makeArtifact("rule", null, "cursorrules", cursorRules, true));
+	}
+	for (const child of entries(root)) {
+		const childPath = join(root, child.name);
+		if (child.isFile() && child.name.endsWith(FILE_EXT) && !child.name.startsWith(".")) {
+			if (matcher(child.name, false)) continue;
+			out.push(makeArtifact(kind, null, child.name.slice(0, -4), childPath, true));
+		} else if (child.isDirectory() && !child.name.startsWith(".") && !ROOT_SKIP.has(child.name)) {
+			if (matcher(child.name, true)) continue;
+			for (const item of entries(childPath)) {
+				const itemPath = join(childPath, item.name);
+				if (item.isFile() && item.name.endsWith(FILE_EXT)) {
+					if (matcher(rel(root, itemPath), false)) continue;
+					out.push(makeArtifact(kind, child.name, item.name.slice(0, -4), itemPath, true));
+				}
+			}
+		}
+	}
+}
+function collectRootProfiles(root, out, matcher) {
+	const localProfileDir = join(root, "profile");
+	if (existsSync(localProfileDir) && !matcher("profile", true)) collectProfiles(root, localProfileDir, out, matcher);
+	for (const child of entries(root)) {
+		if (!child.isFile()) continue;
+		if (matcher(child.name, false)) continue;
+		const lower = child.name.toLowerCase();
+		if (lower === "profile.yaml" || lower === "profile.yml" || lower.endsWith(".profile.yaml") || lower.endsWith(".profile.yml")) {
+			const stem = child.name.replace(/\.(profile\.)?(yaml|yml)$/i, "");
+			out.push(makeArtifact("profile", null, stem, join(root, child.name), true));
+		}
+	}
+}
+function collectRootScripts(root, out, matcher) {
+	const localScriptDir = join(root, "script");
+	if (existsSync(localScriptDir) && !matcher("script", true)) collectScripts(root, localScriptDir, out, matcher);
+	if (!existsSync(join(root, SKILL_MARKER))) {
+		for (const sf of [
+			"run.sh",
+			"script.sh",
+			"run.js",
+			"main.py"
+		]) if (existsSync(join(root, sf)) && !matcher(sf, false)) {
+			const name = basename(root) || "script";
+			out.push(makeArtifact("script", null, name, root, false));
+			break;
+		}
 	}
 }
 function listKind(root, kind) {
 	const out = [];
+	const matcher = createIgnoreMatcher(root);
 	const base = join(root, KIND_DIRS[kind]);
-	if (existsSync(base)) if (kind === "skill") collectSkills(base, out);
-	else if (kind === "profile") collectProfiles(base, out);
-	else if (kind === "script") collectScripts(base, out);
-	else collectMdc(kind, base, out);
-	if (kind === "skill") collectRootSkills(root, out);
-	else if (kind === "agent" || kind === "rule") collectRootMdc(kind, root, out);
+	if (existsSync(base) && !matcher(KIND_DIRS[kind], true)) if (kind === "skill") collectSkills(root, base, out, matcher);
+	else if (kind === "profile") collectProfiles(root, base, out, matcher);
+	else if (kind === "script") collectScripts(root, base, out, matcher);
+	else collectMdc(root, kind, base, out, matcher);
+	if (kind === "skill") collectRootSkills(root, out, matcher);
+	else if (kind === "agent" || kind === "rule") collectRootMdc(kind, root, out, matcher);
+	else if (kind === "profile") collectRootProfiles(root, out, matcher);
+	else if (kind === "script") collectRootScripts(root, out, matcher);
 	const seen = /* @__PURE__ */ new Set();
 	return out.filter((a) => seen.has(a.id) ? false : seen.add(a.id)).sort((a, b) => a.id.localeCompare(b.id));
 }
@@ -371,7 +599,8 @@ function listAll(root) {
 		"skill",
 		"rule",
 		"agent",
-		"profile"
+		"profile",
+		"script"
 	].flatMap((k) => listKind(root, k));
 }
 function select(root, kind, selector) {
@@ -382,6 +611,14 @@ function select(root, kind, selector) {
 	if (byCategory.length) return byCategory;
 	return items.filter((a) => a.name === selector);
 }
+function selectAll(root, selector) {
+	const items = listAll(root);
+	if (!selector) return items;
+	if (selector.includes("/")) return items.filter((a) => a.id === selector);
+	const byCategory = items.filter((a) => a.category === selector);
+	if (byCategory.length) return byCategory;
+	return items.filter((a) => a.name === selector);
+}
 const home$1 = homedir();
 const configHome = xdgConfig ?? join(home$1, ".config");
 const codexHome = process.env.CODEX_HOME?.trim() || join(home$1, ".codex");
@@ -563,6 +800,48 @@ function getNonUniversalAgents() {
 	return listAgents().filter((a) => a.skillsDir !== ".agents/skills");
 }
 const home = homedir();
+function copyTreeDereferenced(src, dest, seen = /* @__PURE__ */ new Set(), filter, baseSrc = src) {
+	const st = lstatSync(src);
+	if (st.isSymbolicLink()) {
+		let real;
+		try {
+			real = realpathSync(src);
+		} catch {
+			return;
+		}
+		if (seen.has(real)) return;
+		seen.add(real);
+		copyTreeDereferenced(real, dest, seen, filter, baseSrc);
+		return;
+	}
+	if (st.isDirectory()) {
+		let real;
+		try {
+			real = realpathSync(src);
+		} catch {
+			real = resolve(src);
+		}
+		if (seen.has(real)) return;
+		seen.add(real);
+		mkdirSync(dest, { recursive: true });
+		for (const name of readdirSync(src)) {
+			const childSrc = join(src, name);
+			const relPath = relative(baseSrc, childSrc).replace(/\\/g, "/");
+			let isDir = false;
+			try {
+				isDir = statSync(childSrc).isDirectory();
+			} catch {}
+			if (DEFAULT_IGNORES.includes(name) || name === ".agentryignore" || name === ".agentry.ignore") continue;
+			if (filter && filter(relPath, isDir)) continue;
+			copyTreeDereferenced(childSrc, join(dest, name), seen, filter, baseSrc);
+		}
+		return;
+	}
+	if (st.isFile()) {
+		mkdirSync(dirname(dest), { recursive: true });
+		copyFileSync(src, dest);
+	}
+}
 function lockBase(opts) {
 	return opts.scope === "global" ? home : opts.dir || process.cwd();
 }
@@ -683,6 +962,7 @@ function installOne(artifact, opts, agentList, source) {
 		});
 		return dests;
 	}
+	const ignoreFilter = artifact.isFile ? void 0 : createIgnoreMatcher(artifact.dir);
 	if (artifact.kind === "skill") {
 		const canonical = join(base, ".agents", "skills", artifact.id);
 		rmSync(canonical, {
@@ -690,7 +970,7 @@ function installOne(artifact, opts, agentList, source) {
 			force: true
 		});
 		mkdirSync(join(canonical, ".."), { recursive: true });
-		cpSync(artifact.dir, canonical, { recursive: true });
+		copyTreeDereferenced(artifact.dir, canonical, /* @__PURE__ */ new Set(), ignoreFilter);
 		for (const a of list) if (a.skillsDir === ".agents/skills") dests.push({
 			agent: a.name,
 			dir: canonical
@@ -703,7 +983,7 @@ function installOne(artifact, opts, agentList, source) {
 			});
 			mkdirSync(join(dir, ".."), { recursive: true });
 			if (opts.copy) {
-				cpSync(canonical, dir, { recursive: true });
+				copyTreeDereferenced(canonical, dir);
 				dests.push({
 					agent: a.name,
 					dir
@@ -716,7 +996,7 @@ function installOne(artifact, opts, agentList, source) {
 					symlinked: true
 				});
 			} catch {
-				cpSync(canonical, dir, { recursive: true });
+				copyTreeDereferenced(canonical, dir);
 				dests.push({
 					agent: a.name,
 					dir
@@ -730,7 +1010,7 @@ function installOne(artifact, opts, agentList, source) {
 			force: true
 		});
 		mkdirSync(join(dir, ".."), { recursive: true });
-		cpSync(artifact.dir, dir, { recursive: true });
+		copyTreeDereferenced(artifact.dir, dir, /* @__PURE__ */ new Set(), ignoreFilter);
 		dests.push({
 			agent: a.name,
 			dir
@@ -1417,6 +1697,98 @@ function agentsPrompt(action) {
 	if (action === "update") return "Which agents do you want to update for?";
 	return "Which agents do you want to install to?";
 }
+function scopePrompt(action) {
+	if (action === "remove") return "Removal scope";
+	if (action === "update") return "Update scope";
+	return "Installation scope";
+}
+async function selectInstallScope(message, paths) {
+	if (isQuiet()) return "project";
+	return new Promise((resolve) => {
+		if (!process.stdin.isTTY) {
+			resolve("project");
+			return;
+		}
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout
+		});
+		process.stdin.setRawMode(true);
+		readline.emitKeypressEvents(process.stdin, rl);
+		let value = "project";
+		let lastH = 0;
+		const joinRel = (base, rel) => {
+			const sep = base.includes("\\") ? "\\" : "/";
+			return `${base.replace(/[\\/]+$/, "")}${sep}${rel.replace(/\//g, sep)}`;
+		};
+		const optionBlock = (key, selected, done) => {
+			const active = done ? done === key : selected;
+			const bullet = active ? sky(c.bold("●")) : c.dim("○");
+			const title = key === "project" ? "Project" : "Global";
+			const hint = key === "project" ? "Install in the current directory (committed with your project)" : "Install in your home directory (available across all projects)";
+			const path = key === "project" ? paths.projectDir : paths.homeDir;
+			const lock = key === "project" ? joinRel(paths.projectDir, ".agentry/lock.json") : joinRel(paths.homeDir, ".agentry/lock.json");
+			const lines = [];
+			if (done === "cancel") lines.push(`${c.dim("│")}  ${c.strikethrough(c.dim(title))}`);
+			else {
+				lines.push(`${c.dim("│")}  ${bullet} ${active ? c.bold(title) : title}`);
+				lines.push(`${c.dim("│")}    ${c.dim(hint)}`);
+				lines.push(`${c.dim("│")}    ${sky("→")} ${c.dim(path)}`);
+				lines.push(`${c.dim("│")}    ${c.dim(`lock ${lock}`)}`);
+			}
+			return lines;
+		};
+		const paint = (done) => {
+			const lines = [];
+			if (done === "cancel") {
+				lines.push(`${sky("■")} ${c.bold(message)}`);
+				lines.push(`${c.dim("│")} ${c.strikethrough(c.dim("Cancelled"))}`);
+			} else if (done === "project" || done === "global") {
+				lines.push(`${sky("◇")} ${c.bold(message)}`);
+				lines.push(...optionBlock(done, true, done).slice(0, 2));
+				lines.push(`${c.dim("│")}    ${sky("→")} ${c.dim(done === "project" ? paths.projectDir : paths.homeDir)}`);
+			} else {
+				lines.push(`${sky("◆")} ${c.bold(message)}`);
+				lines.push(`${c.dim("│")}`);
+				lines.push(...optionBlock("project", value === "project"));
+				lines.push(`${c.dim("│")}`);
+				lines.push(...optionBlock("global", value === "global"));
+				lines.push(`${c.dim("└")} ${c.dim("↑/↓ select · enter confirm")}`);
+			}
+			if (lastH > 0) for (let i = 0; i < lastH; i++) process.stdout.write("\x1B[1A\x1B[2K");
+			process.stdout.write(lines.join("\n") + "\n");
+			lastH = lines.length;
+		};
+		const cleanup = () => {
+			process.stdin.removeListener("keypress", onKey);
+			process.stdin.setRawMode(false);
+			rl.close();
+		};
+		const onKey = (_s, key) => {
+			if (!key) return;
+			if (key.name === "up" || key.name === "down" || key.name === "tab") {
+				value = value === "project" ? "global" : "project";
+				paint();
+				return;
+			}
+			if (key.name === "return") {
+				paint(value);
+				cleanup();
+				blank();
+				resolve(value);
+				return;
+			}
+			if (key.name === "escape" || key.ctrl && key.name === "c") {
+				paint("cancel");
+				cleanup();
+				resolve(null);
+			}
+		};
+		process.stdin.on("keypress", onKey);
+		blank();
+		paint();
+	});
+}
 function isQuiet() {
 	return isCI() || !process.stdout.isTTY;
 }
@@ -1784,7 +2156,7 @@ async function cmdAdd(kind, source, selector, opts) {
 	await delayQuiet(280);
 	const { root, cleanup } = await resolveSourceWithUi(source, opts);
 	try {
-		const artifacts = await spinner("Discovering…", () => kind === "all" ? listAll(root) : select(root, kind, selector), (a) => {
+		const artifacts = await spinner("Discovering…", () => kind === "all" ? selector ? selectAll(root, selector) : listAll(root) : select(root, kind, selector), (a) => {
 			const noun = kind === "all" ? "artifact" : kind;
 			return `Found ${a.length} ${noun}${a.length === 1 ? "" : "s"}`;
 		}, 620);
@@ -1799,22 +2171,28 @@ async function cmdAdd(kind, source, selector, opts) {
 			return;
 		}
 		let chosen = artifacts;
-		if (!selector && kind !== "all" && artifacts.length > 1 && !opts.all && !opts.yes && !isQuiet()) {
-			await sectionTransition("source discovery", `select ${kind}s to install`);
-			const picked = await selectArtifacts(`Select ${kind}s to install`, artifacts);
+		if (!selector && artifacts.length > 1 && !opts.all && !opts.yes && !isQuiet()) {
+			const noun = kind === "all" ? "artifacts" : `${kind}s`;
+			await sectionTransition("source discovery", `select ${noun} to install`);
+			const picked = await selectArtifacts(`Select ${noun} to install`, artifacts);
 			if (isCancelLike(picked)) {
 				outro("Cancelled.");
 				return;
 			}
 			chosen = picked;
-			await sectionTransition(`${chosen.length} ${kind}${chosen.length === 1 ? "" : "s"} selected`, "choose target agents");
-		} else if (!isQuiet() && !opts.agents.length && !opts.all && !opts.yes) await sectionTransition(`${chosen.length} ${kind}${chosen.length === 1 ? "" : "s"} ready`, "choose target agents");
-		else {
+			await sectionTransition(`${chosen.length} ${chosen.length === 1 ? "artifact" : "artifacts"} selected`, "choose target agents");
+		} else if (!isQuiet() && !opts.agents.length && !opts.all && !opts.yes) {
+			const noun = kind === "all" ? chosen.length === 1 ? "artifact" : "artifacts" : `${kind}${chosen.length === 1 ? "" : "s"}`;
+			await sectionTransition(`${chosen.length} ${noun} ready`, "choose target agents");
+		} else {
 			await delayQuiet(200);
 			blank();
 		}
 		const agentList = await resolveAgentList(opts, "install");
-		if (!isQuiet() && !opts.agents.length && !opts.all && !opts.yes) await sectionTransition(`${agentList.length} agent${agentList.length === 1 ? "" : "s"} selected`, "install summary");
+		const askScope = !opts.scopeExplicit && !opts.yes && !isQuiet();
+		if (!isQuiet() && !opts.agents.length && !opts.all && !opts.yes) await sectionTransition(`${agentList.length} agent${agentList.length === 1 ? "" : "s"} selected`, askScope ? "installation scope" : "install summary");
+		if (!await ensureInstallScope(opts, "install")) return;
+		if (askScope) await sectionTransition("scope set", "install summary");
 		installAll(chosen, opts, agentList, source);
 	} finally {
 		cleanup();
@@ -1833,6 +2211,7 @@ async function cmdAddProfile(name, source, opts) {
 	const repo = source || (profile.artifacts.skills[0]?.source ?? profile.artifacts.rules[0]?.source);
 	if (!repo) throw new Error(`No source given and ${file} lists none. Try: agentry add profile ${name} author/repo`);
 	const agentList = await resolveAgentList(opts, "install");
+	if (!await ensureInstallScope(opts, "install")) return;
 	const { root, cleanup } = await resolveSourceWithUi(repo, opts);
 	try {
 		const artifacts = [];
@@ -1878,6 +2257,23 @@ async function resolveAgentList(opts, action = "install") {
 	if (isCancelLike(selected)) throw new Error("Cancelled.");
 	return selected;
 }
+async function ensureInstallScope(opts, action) {
+	if (opts.scopeExplicit) return true;
+	if (opts.yes || isQuiet()) return true;
+	const { homedir } = await import("node:os");
+	if (!isQuiet()) await sectionTransition(`${action === "install" ? "agents" : action} ready`, scopePrompt(action).toLowerCase());
+	const picked = await selectInstallScope(scopePrompt(action), {
+		projectDir: opts.dir || process.cwd(),
+		homeDir: homedir()
+	});
+	if (picked == null || isCancelLike(picked)) {
+		outro("Cancelled.");
+		return false;
+	}
+	opts.scope = picked;
+	opts.scopeExplicit = true;
+	return true;
+}
 function installAll(artifacts, opts, agentList, source) {
 	if (!artifacts.length) {
 		warn("Nothing matched - nothing installed.");
@@ -1904,8 +2300,22 @@ function resolveSourceOrSelector(arg1, arg2, opts) {
 	if (!arg1) return {};
 	if (isExplicitSource(arg1)) return { source: arg1 };
 	if (isOwnerRepoShape(arg1)) {
-		const lock = readLock(toInstallOpts(opts));
-		if (Object.values(lock.items).some((e) => e.source && sourcesEqual(e.source, arg1))) return { source: arg1 };
+		const bases = [{
+			scope: "project",
+			dir: opts.dir,
+			agents: opts.agents,
+			copy: opts.copy,
+			dryRun: opts.dryRun
+		}, {
+			scope: "global",
+			agents: opts.agents,
+			copy: opts.copy,
+			dryRun: opts.dryRun
+		}];
+		for (const base of bases) {
+			const lock = readLock(base);
+			if (Object.values(lock.items).some((e) => e.source && sourcesEqual(e.source, arg1))) return { source: arg1 };
+		}
 	}
 	return { selector: arg1 };
 }
@@ -1918,6 +2328,7 @@ async function cmdRemove(kind, arg1, arg2, opts) {
 	}, 420);
 	if (!isQuiet() && !opts.agents.length && !opts.all && !opts.yes) await sectionTransition("prepare remove", "choose agents to remove from");
 	const agentList = await resolveAgentList(opts, "remove");
+	if (!await ensureInstallScope(opts, "remove")) return;
 	const installOpts = toInstallOpts(opts);
 	const scope = [
 		kind,
@@ -1928,7 +2339,7 @@ async function cmdRemove(kind, arg1, arg2, opts) {
 		let count = 0;
 		let paths = 0;
 		for (const t of ARTIFACT_KINDS) {
-			const r = removeSelection(t, void 0, installOpts, agentList, source);
+			const r = removeSelection(t, selector, installOpts, agentList, source);
 			count += r.removedKeys.length;
 			paths += r.removedPaths.length;
 		}
@@ -1959,7 +2370,7 @@ async function cmdList(source, kind, selector, opts) {
 	try {
 		printArtifactList(await spinner("Discovering…", () => {
 			if (kind) return select(root, kind, selector);
-			return listAll(root);
+			return selector ? selectAll(root, selector) : listAll(root);
 		}, (a) => `Found ${a.length} artifact${a.length === 1 ? "" : "s"}`, 520), {
 			title: "Available in source",
 			subtitle: source
@@ -2051,7 +2462,6 @@ function printArtifactList(artifacts, meta) {
 async function cmdUpdateAssets(kind, arg1, arg2, opts) {
 	intro();
 	const { source, selector } = resolveSourceOrSelector(arg1, arg2, opts);
-	const installOpts = toInstallOpts(opts);
 	if (source) {
 		await spinner("Parsing source…", () => parseSource(source), (p) => {
 			const where = p.url || p.local || source;
@@ -2059,23 +2469,28 @@ async function cmdUpdateAssets(kind, arg1, arg2, opts) {
 		}, 520);
 		const { root, cleanup } = await resolveSourceWithUi(source, opts);
 		try {
-			const artifacts = await spinner("Discovering…", () => kind === "all" ? listAll(root) : select(root, kind, selector), (a) => `Found ${a.length} to update`, 620);
+			const artifacts = await spinner("Discovering…", () => kind === "all" ? selector ? selectAll(root, selector) : listAll(root) : select(root, kind, selector), (a) => `Found ${a.length} to update`, 620);
 			if (!artifacts.length) {
 				warn(`Nothing found in ${source}.`);
 				return;
 			}
 			let chosen = artifacts;
-			if (!selector && kind !== "all" && artifacts.length > 1 && !opts.all && !opts.yes && !isQuiet()) {
-				await sectionTransition("source discovery", `select ${kind}s to update`);
-				const picked = await selectArtifacts(`Select ${kind}s to update`, artifacts);
+			if (!selector && artifacts.length > 1 && !opts.all && !opts.yes && !isQuiet()) {
+				const noun = kind === "all" ? "artifacts" : `${kind}s`;
+				await sectionTransition("source discovery", `select ${noun} to update`);
+				const picked = await selectArtifacts(`Select ${noun} to update`, artifacts);
 				if (isCancelLike(picked)) {
 					outro("Cancelled.");
 					return;
 				}
 				chosen = picked;
-				await sectionTransition(`${chosen.length} ${kind}${chosen.length === 1 ? "" : "s"} selected`, "choose target agents");
-			} else if (!isQuiet() && !opts.agents.length && !opts.all && !opts.yes) await sectionTransition(`${chosen.length} ${kind}${chosen.length === 1 ? "" : "s"} ready`, "choose target agents");
+				await sectionTransition(`${chosen.length} ${chosen.length === 1 ? "artifact" : "artifacts"} selected`, "choose target agents");
+			} else if (!isQuiet() && !opts.agents.length && !opts.all && !opts.yes) {
+				const noun = kind === "all" ? chosen.length === 1 ? "artifact" : "artifacts" : `${kind}${chosen.length === 1 ? "" : "s"}`;
+				await sectionTransition(`${chosen.length} ${noun} ready`, "choose target agents");
+			}
 			const agentList = await resolveAgentList(opts, "update");
+			if (!await ensureInstallScope(opts, "update")) return;
 			if (!isQuiet() && !opts.agents.length && !opts.all && !opts.yes) await sectionTransition(`${agentList.length} agent${agentList.length === 1 ? "" : "s"} selected`, "update summary");
 			installAll(chosen, opts, agentList, source);
 		} finally {
@@ -2083,7 +2498,8 @@ async function cmdUpdateAssets(kind, arg1, arg2, opts) {
 		}
 		return;
 	}
-	let installed = listInstalled(installOpts).filter((it) => kind === "all" || it.id.startsWith(kind + "/"));
+	if (!await ensureInstallScope(opts, "update")) return;
+	let installed = listInstalled(toInstallOpts(opts)).filter((it) => kind === "all" || it.id.startsWith(kind + "/"));
 	if (selector) {
 		const rel = `${kind}/${selector}`;
 		installed = installed.filter((it) => it.id === rel || it.id.startsWith(rel + "/") || it.id.endsWith("/" + selector));
@@ -2308,6 +2724,7 @@ function takeOptValue(argv, i) {
 function parseArgs(argv) {
 	const opts = {
 		scope: "project",
+		scopeExplicit: false,
 		agents: [],
 		copy: false,
 		dryRun: false,
@@ -2321,15 +2738,19 @@ function parseArgs(argv) {
 		const a = argv[i];
 		if (a === "-g" || a === "--global") {
 			opts.scope = "global";
+			opts.scopeExplicit = true;
 			flags.global = true;
-		} else if (a === "--project") {
+		} else if (a === "-p" || a === "--project") {
 			opts.scope = "project";
+			opts.scopeExplicit = true;
 			flags.project = true;
 		} else if (a === "-y" || a === "--yes") {
 			opts.yes = true;
 			flags.yes = true;
-		} else if (a === "--dir") {
+		} else if (a === "-d" || a === "--dir") {
 			opts.dir = argv[++i];
+			opts.scope = "project";
+			opts.scopeExplicit = true;
 			flags.dir = opts.dir;
 		} else if (a === "-a" || a === "--agent") {
 			opts.agents.push(argv[++i]);
@@ -2420,7 +2841,11 @@ async function runUpdateSelf() {
 function runNpmInstall(spec) {
 	spinner(`Updating agentry CLI`, () => {
 		try {
-			execSync(`npm install -g ${spec}`, { stdio: "inherit" });
+			execFileSync("npm", [
+				"install",
+				"-g",
+				spec
+			], { stdio: "inherit" });
 		} catch {
 			err("Update failed. Once published, run: npm install -g " + spec);
 			process.exit(1);
@@ -2430,7 +2855,11 @@ function runNpmInstall(spec) {
 function runUninstall() {
 	spinner("Uninstalling agentry CLI", () => {
 		try {
-			execSync(`npm uninstall -g ${name}`, { stdio: "inherit" });
+			execFileSync("npm", [
+				"uninstall",
+				"-g",
+				name
+			], { stdio: "inherit" });
 		} catch {
 			err("Uninstall failed. Try: npm uninstall -g " + name);
 			process.exit(1);
@@ -2489,21 +2918,33 @@ async function main() {
 		return;
 	}
 	if (action === "add") {
-		const kind = positional[1] ? normalizeKind(positional[1]) : void 0;
-		if (!kind) throw new Error("Missing kind. e.g. agentry add skills author/repo");
-		if (kind === "profile") {
+		const a1 = positional[1];
+		if (!a1) throw new Error("Missing source or kind. e.g. agentry add author/repo or agentry add skills author/repo");
+		const k1 = normalizeKind(a1);
+		if (k1 === "profile") {
 			await cmdAddProfile(positional[2], positional[3], opts);
 			return;
 		}
-		if (kind !== "all" && !isKind(kind)) throw new Error(`Unknown kind: ${kind}`);
-		await cmdAdd(kind, positional[2], positional[3], opts);
+		if (k1 === "all" || isKind(k1)) {
+			const source = positional[2];
+			if (!source) throw new Error(`Missing source. e.g. agentry add ${k1} author/repo`);
+			await cmdAdd(k1, source, positional[3], opts);
+			return;
+		}
+		const source = a1;
+		const selector = positional[2];
+		await cmdAdd("all", source, selector, opts);
 		return;
 	}
 	if (action === "remove" || action === "rm") {
-		const kind = positional[1] ? normalizeKind(positional[1]) : void 0;
-		if (!kind) throw new Error("Missing kind. e.g. agentry remove skills enhance-prompt");
-		if (kind !== "all" && !isKind(kind)) throw new Error(`Unknown kind: ${kind}`);
-		await cmdRemove(kind, positional[2], positional[3], opts);
+		const a1 = positional[1];
+		if (!a1) throw new Error("Missing kind or selector. e.g. agentry remove skills enhance-prompt");
+		const k1 = normalizeKind(a1);
+		if (k1 === "all" || isKind(k1)) {
+			await cmdRemove(k1, positional[2], positional[3], opts);
+			return;
+		}
+		await cmdRemove("all", positional[1], positional[2], opts);
 		return;
 	}
 	if (action === "init") {