@iseoane/agent-depot 0.2.0 → 0.3.0

package/dist/src/user-global-skill-inventory.js

@@ -0,0 +1,565 @@
+import { lstat, readdir, readFile, readlink, rename, rm, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import path from "node:path";
+import { assertSkillNotAppOwned, loadAppOwnedSkillFilter } from "./app-owned-skills.js";
+import { pathsOverlap } from "./path-safety.js";
+import { readExistingSkillTree } from "./skill-adoption.js";
+import { parseSkillFrontmatter, skillTreeBaseline } from "./skill-discovery.js";
+const GLOBAL_SKILL_ROOTS = [
+    { kind: "agents", relativePath: [".agents", "skills"] },
+    { kind: "claude", relativePath: [".claude", "skills"] },
+];
+const nodeFileSystem = {
+    lstat,
+    readdir: async (candidatePath) => readdir(candidatePath),
+    readFile,
+    rename,
+    rm,
+};
+/**
+ * Scans only the immediate real directories below the two supported global Skill
+ * roots. This operation never reads a Skill tree or changes the filesystem.
+ *
+ * A persisted installation location is the ownership identity. Its normalized
+ * absolute path is compared directly, which preserves noncanonical adopted
+ * locations instead of guessing ownership from a Skill name alone.
+ */
+export async function scanUserGlobalSkillInventory(options = {}) {
+    const homeDirectory = path.resolve(options.homeDirectory ?? homedir());
+    const selections = options.managedInstallations ?? options.managedSelections ?? [];
+    const managedPaths = new Set();
+    const managedCanonicalPaths = new Set();
+    for (const selection of selections) {
+        const installationPath = selection.installation?.path;
+        if (installationPath === undefined)
+            continue;
+        const absolutePath = resolveInstallationPath(homeDirectory, installationPath);
+        if (absolutePath === undefined)
+            continue;
+        managedPaths.add(pathKey(absolutePath));
+        // Only a persisted canonical location is authoritative for deduplicating
+        // an exposure symlink. A Claude-only adopted directory is deliberately not
+        // treated as ownership of a same-name canonical directory: that separate
+        // real directory must remain visible as a possible duplicate.
+        if (isUnderGlobalRoot(absolutePath, homeDirectory, ".agents")) {
+            managedCanonicalPaths.add(pathKey(absolutePath));
+        }
+    }
+    const entries = [];
+    const skipped = [];
+    const exposures = [];
+    const symlinks = [];
+    const isAppOwned = await loadAppOwnedSkillFilter({ ...options, homeDirectory });
+    const state = { isAppOwned, managedPaths, managedCanonicalPaths, entries, skipped, exposures, symlinks };
+    for (const root of GLOBAL_SKILL_ROOTS) {
+        const rootPath = path.join(homeDirectory, ...root.relativePath);
+        await scanRoot(root, rootPath, homeDirectory, state);
+    }
+    const managed = entries.filter((entry) => entry.status === "managed");
+    const unmanaged = entries.filter((entry) => entry.status === "unmanaged");
+    return Object.freeze({
+        homeDirectory,
+        entries: Object.freeze(entries),
+        managed: Object.freeze(managed),
+        unmanaged: Object.freeze(unmanaged),
+        skipped: Object.freeze(skipped),
+        exposures: Object.freeze(exposures),
+        symlinks: Object.freeze(symlinks),
+    });
+}
+/** Short alias for callers that only need the inventory operation. */
+export const scanUserGlobalSkills = scanUserGlobalSkillInventory;
+async function scanRoot(root, rootPath, homeDirectory, state) {
+    const names = await listScannableRoot(root, rootPath, homeDirectory, state.skipped);
+    for (const name of names ?? []) {
+        await scanRootEntry(root, name, path.join(rootPath, name), homeDirectory, state);
+    }
+}
+/** Returns the sorted entry names of a safe root, or undefined when it is missing or reported as skipped. */
+async function listScannableRoot(root, rootPath, homeDirectory, skipped) {
+    const ancestorSafety = await inspectGlobalRootAncestors(homeDirectory, rootPath);
+    if (ancestorSafety === "missing")
+        return undefined;
+    if (ancestorSafety !== undefined) {
+        skipped.push(skip(rootPath, root.kind, "unsafe-root", ancestorSafety));
+        return undefined;
+    }
+    let rootInformation;
+    try {
+        rootInformation = await lstat(rootPath);
+    }
+    catch (error) {
+        if (!isMissing(error))
+            skipped.push(skip(rootPath, root.kind, "unsafe-root", errorMessage(error)));
+        return undefined;
+    }
+    if (rootInformation.isSymbolicLink() || !rootInformation.isDirectory()) {
+        skipped.push(skip(rootPath, root.kind, "unsafe-root", "global Skill root is not a real directory"));
+        return undefined;
+    }
+    try {
+        return (await readdir(rootPath)).sort();
+    }
+    catch (error) {
+        skipped.push(skip(rootPath, root.kind, "unsafe-root", errorMessage(error)));
+        return undefined;
+    }
+}
+async function scanRootEntry(root, name, candidatePath, homeDirectory, state) {
+    const { managedPaths, entries, skipped } = state;
+    if (!managedPaths.has(pathKey(candidatePath)) && state.isAppOwned(name))
+        return;
+    if (isTransientName(name)) {
+        skipped.push({ name, path: candidatePath, root: root.kind, reason: "excluded-transient" });
+        return;
+    }
+    let information;
+    try {
+        // lstat is deliberate: neither an entry nor any ancestor below the root
+        // is followed while deciding whether it is eligible for removal.
+        information = await lstat(candidatePath);
+    }
+    catch (error) {
+        if (!isMissing(error))
+            skipped.push(skip(candidatePath, root.kind, "unsafe-entry", errorMessage(error), name));
+        return;
+    }
+    if (information.isSymbolicLink()) {
+        await classifySymlink(candidatePath, name, root.kind, homeDirectory, state);
+        return;
+    }
+    if (!information.isDirectory())
+        return;
+    const problem = await findSkillDirectoryProblem(candidatePath);
+    if (problem === "not-a-skill")
+        return;
+    if (problem !== undefined) {
+        skipped.push(skip(candidatePath, root.kind, problem.reason, problem.detail, name));
+        return;
+    }
+    entries.push(Object.freeze({
+        name,
+        path: candidatePath,
+        root: root.kind,
+        host: root.kind === "claude" ? "claude" : "shared",
+        status: managedPaths.has(pathKey(candidatePath)) ? "managed" : "unmanaged",
+    }));
+}
+/** Why a real directory is not an eligible Skill: silently "not-a-skill" (no SKILL.md) or a reported problem. */
+async function findSkillDirectoryProblem(candidatePath) {
+    const skillFile = path.join(candidatePath, "SKILL.md");
+    let skillFileInformation;
+    try {
+        skillFileInformation = await lstat(skillFile);
+    }
+    catch (error) {
+        return isMissing(error) ? "not-a-skill" : { reason: "unsafe-skill-file", detail: errorMessage(error) };
+    }
+    if (skillFileInformation.isSymbolicLink() || !skillFileInformation.isFile()) {
+        return { reason: "unsafe-skill-file", detail: "SKILL.md is not a real file" };
+    }
+    let skillContent;
+    try {
+        skillContent = await readFile(skillFile);
+    }
+    catch (error) {
+        return { reason: "unsafe-skill-file", detail: `SKILL.md cannot be read: ${errorMessage(error)}` };
+    }
+    if (parseSkillFrontmatter(Buffer.from(skillContent).toString("utf8")) === undefined) {
+        return { reason: "unsafe-skill-file", detail: "SKILL.md does not contain valid top-level name and description frontmatter" };
+    }
+    const unsafeTreeEntry = await findUnsafeTreeEntry(candidatePath);
+    return unsafeTreeEntry === undefined ? undefined : { reason: "unsafe-entry", detail: unsafeTreeEntry };
+}
+async function classifySymlink(candidatePath, name, root, homeDirectory, state) {
+    const { managedCanonicalPaths, managedPaths, entries, skipped, exposures, symlinks } = state;
+    let linkTarget;
+    try {
+        linkTarget = await readlink(candidatePath);
+    }
+    catch (error) {
+        skipped.push(skip(candidatePath, root, "unsafe-entry", errorMessage(error), name));
+        return;
+    }
+    const resolvedTarget = path.resolve(path.dirname(candidatePath), linkTarget);
+    // Only an exact same-name link to a direct child of the canonical root can be
+    // an exposure created by Agent Depot; anything else stays reported.
+    const isSameNameCanonical = root === "claude" &&
+        isUnderGlobalRoot(resolvedTarget, homeDirectory, ".agents") &&
+        path.basename(resolvedTarget) === name &&
+        pathKey(path.dirname(resolvedTarget)) === pathKey(path.join(homeDirectory, ".agents", "skills"));
+    const isManagedAlias = isSameNameCanonical &&
+        (managedCanonicalPaths.has(pathKey(resolvedTarget)) || managedPaths.has(pathKey(candidatePath)));
+    const isListedCanonical = isSameNameCanonical &&
+        entries.some((entry) => entry.root === "agents" && pathKey(entry.path) === pathKey(resolvedTarget));
+    if (isManagedAlias || isListedCanonical) {
+        const targetSafety = await inspectCanonicalTarget(resolvedTarget);
+        if (targetSafety === undefined) {
+            exposures.push({ name, path: candidatePath, root, target: resolvedTarget });
+            return;
+        }
+        skipped.push(skip(candidatePath, root, "unsafe-entry", targetSafety, name));
+        return;
+    }
+    skipped.push(skip(candidatePath, root, "unsafe-entry", "symbolic-link entries are never removal candidates", name));
+    if (!managedPaths.has(pathKey(candidatePath)))
+        symlinks.push({ name, path: candidatePath, root, target: resolvedTarget });
+}
+async function findUnsafeTreeEntry(candidatePath, relativeDirectory = "") {
+    let names;
+    try {
+        names = await readdir(candidatePath);
+    }
+    catch (error) {
+        return `Skill tree could not be inspected: ${errorMessage(error)}`;
+    }
+    for (const name of [...names].sort()) {
+        const relativePath = relativeDirectory === "" ? name : `${relativeDirectory}/${name}`;
+        const childPath = path.join(candidatePath, name);
+        let information;
+        try {
+            information = await lstat(childPath);
+        }
+        catch (error) {
+            return `Skill tree entry ${relativePath} could not be inspected: ${errorMessage(error)}`;
+        }
+        if (information.isSymbolicLink())
+            return `Skill tree contains a symbolic link: ${relativePath}`;
+        if (information.isDirectory()) {
+            const nested = await findUnsafeTreeEntry(childPath, relativePath);
+            if (nested !== undefined)
+                return nested;
+            continue;
+        }
+        if (!information.isFile())
+            return `Skill tree contains a non-regular file: ${relativePath}`;
+    }
+    return undefined;
+}
+async function inspectGlobalRootAncestors(homeDirectory, rootPath) {
+    const relative = path.relative(homeDirectory, rootPath);
+    if (relative === "" || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        return "global Skill root has an unsafe ancestor";
+    }
+    let current = homeDirectory;
+    for (const segment of ["", ...relative.split(path.sep)]) {
+        if (segment !== "")
+            current = path.join(current, segment);
+        let information;
+        try {
+            information = await lstat(current);
+        }
+        catch (error) {
+            if (isMissing(error))
+                return "missing";
+            return errorMessage(error);
+        }
+        if (information.isSymbolicLink() || !information.isDirectory()) {
+            return `global Skill root ancestor is not a real directory: ${current}`;
+        }
+    }
+    return undefined;
+}
+async function inspectCanonicalTarget(candidatePath) {
+    let targetInformation;
+    try {
+        targetInformation = await lstat(candidatePath);
+    }
+    catch (error) {
+        return `managed canonical target is unavailable: ${errorMessage(error)}`;
+    }
+    if (targetInformation.isSymbolicLink() || !targetInformation.isDirectory()) {
+        return "managed canonical target is not a real directory";
+    }
+    let skillInformation;
+    try {
+        skillInformation = await lstat(path.join(candidatePath, "SKILL.md"));
+    }
+    catch (error) {
+        return `managed canonical Skill file is unavailable: ${errorMessage(error)}`;
+    }
+    if (skillInformation.isSymbolicLink() || !skillInformation.isFile()) {
+        return "managed canonical target does not contain a real SKILL.md file";
+    }
+    return undefined;
+}
+/**
+ * Inspects one explicit unmanaged global path without resolving or searching a
+ * Source. The complete tree must be real-directory/regular-file content so a
+ * later recursive delete cannot follow a link or special file.
+ */
+export async function inspectUserGlobalSkillRemoval(candidatePath, options) {
+    const homeDirectory = path.resolve(options.homeDirectory);
+    const targetPath = validateExplicitGlobalPath(candidatePath, homeDirectory);
+    await assertSkillNotAppOwned(path.basename(candidatePath), options);
+    const fileSystem = options.fileSystem ?? nodeFileSystem;
+    await assertRealGlobalAncestors(homeDirectory, path.dirname(targetPath), fileSystem);
+    const managedPaths = managedProtectionPaths(homeDirectory, options.managedInstallations);
+    const managedPath = managedPaths.find((protectedPath) => pathsOverlap(pathKey(targetPath), pathKey(protectedPath)));
+    if (managedPath !== undefined) {
+        throw new Error(`Cannot remove ${JSON.stringify(targetPath)} because it is managed or aliases a managed installation at ${JSON.stringify(managedPath)}; no path was changed`);
+    }
+    const information = await realDirectory(targetPath, "selected unmanaged Skill", fileSystem);
+    const skillFile = path.join(targetPath, "SKILL.md");
+    const skillInformation = await fileSystem.lstat(skillFile);
+    if (skillInformation.isSymbolicLink() || !skillInformation.isFile()) {
+        throw new Error(`Selected unmanaged Skill must contain a real SKILL.md file: ${targetPath}; no path was changed`);
+    }
+    const skillContent = await fileSystem.readFile(skillFile);
+    if (parseSkillFrontmatter(Buffer.from(skillContent).toString("utf8")) === undefined) {
+        throw new Error(`Selected unmanaged Skill must contain valid top-level name and description frontmatter: ${targetPath}; no path was changed`);
+    }
+    const tree = await readUnmanagedTree(targetPath, path.basename(targetPath), fileSystem);
+    return Object.freeze({
+        name: path.basename(targetPath),
+        path: targetPath,
+        identity: fileIdentity(information),
+        digest: skillTreeBaseline(tree).digest,
+    });
+}
+/** Refuses selected unmanaged paths that overlap physically or through Host aliases. */
+export function assertNoOverlappingUserGlobalSkillRemovals(inspections) {
+    for (let leftIndex = 0; leftIndex < inspections.length; leftIndex += 1) {
+        for (let rightIndex = leftIndex + 1; rightIndex < inspections.length; rightIndex += 1) {
+            const left = inspections[leftIndex];
+            const right = inspections[rightIndex];
+            const leftAliases = globalPathAliases(left.path);
+            const rightAliases = globalPathAliases(right.path);
+            if (leftAliases.some((candidate) => rightAliases.some((other) => pathsOverlap(pathKey(candidate), pathKey(other))))) {
+                throw new Error(`Cannot remove selected unmanaged Skills because their paths or canonical/Claude aliases overlap: ${JSON.stringify(left.path)} and ${JSON.stringify(right.path)}; no path was changed`);
+            }
+        }
+    }
+}
+/**
+ * Rechecks an inspected unmanaged Skill, moves it to same-parent staging, and
+ * permanently deletes only after validating the moved tree. A drifted or
+ * unverifiable staged tree is retained rather than guessed at.
+ */
+export async function removeUserGlobalSkill(inspection, options) {
+    const current = await inspectUserGlobalSkillRemoval(inspection.path, options);
+    if (current.name !== inspection.name || current.path !== inspection.path || current.identity !== inspection.identity || current.digest !== inspection.digest) {
+        throw new Error(`The inspected unmanaged Skill changed before deletion: ${JSON.stringify(inspection.path)}; no path was changed`);
+    }
+    let removalOptions = options;
+    if (options.readManagedInstallations !== undefined) {
+        const latestManagedInstallations = await options.readManagedInstallations();
+        if (options.expectedManagedInstallations !== undefined && !sameManagedInstallations(options.expectedManagedInstallations, latestManagedInstallations)) {
+            throw new Error(`Managed Skill records changed before deleting unmanaged Skill ${JSON.stringify(inspection.path)}; no path was changed`);
+        }
+        const latest = await inspectUserGlobalSkillRemoval(inspection.path, {
+            ...options,
+            managedInstallations: latestManagedInstallations,
+        });
+        if (latest.name !== inspection.name || latest.path !== inspection.path || latest.identity !== inspection.identity || latest.digest !== inspection.digest) {
+            throw new Error(`The inspected unmanaged Skill changed before deletion: ${JSON.stringify(inspection.path)}; no path was changed`);
+        }
+        removalOptions = { ...options, managedInstallations: latestManagedInstallations };
+    }
+    const fileSystem = removalOptions.fileSystem ?? nodeFileSystem;
+    const stagingPath = path.join(path.dirname(inspection.path), `.${inspection.name}.agent-depot-unmanaged-stage-${randomUUID()}`);
+    try {
+        await fileSystem.rename(inspection.path, stagingPath);
+    }
+    catch (error) {
+        throw new Error(`Could not stage unmanaged Skill ${JSON.stringify(inspection.path)} before deletion: ${errorMessage(error)}; no path was changed`);
+    }
+    try {
+        const staged = await inspectStagedSkill(stagingPath, inspection.name, fileSystem);
+        if (staged.identity !== inspection.identity || staged.digest !== inspection.digest) {
+            throw new Error("the staged tree's identity or content changed");
+        }
+        await fileSystem.rm(stagingPath, { recursive: true, force: false });
+    }
+    catch (error) {
+        const restored = await restoreStagedSkill(stagingPath, inspection.path, inspection, fileSystem);
+        if (restored) {
+            throw new Error(`Unmanaged Skill deletion stopped for ${JSON.stringify(inspection.path)}; the original was restored and no permanent deletion occurred: ${errorMessage(error)}`);
+        }
+        throw new Error(`Unmanaged Skill deletion status is uncertain for ${JSON.stringify(inspection.path)}; staged path retained at ${JSON.stringify(stagingPath)} and recovery is not guaranteed: ${errorMessage(error)}`);
+    }
+}
+/**
+ * Inspects one explicit symlink below a supported global root. Only the link is
+ * ever removed; the path it points to is never read, followed or changed.
+ */
+export async function inspectUserGlobalSymlinkRemoval(candidatePath, options) {
+    const homeDirectory = path.resolve(options.homeDirectory);
+    const linkPath = validateExplicitGlobalPath(candidatePath, homeDirectory);
+    await assertSkillNotAppOwned(path.basename(candidatePath), options);
+    const fileSystem = options.fileSystem ?? nodeFileSystem;
+    await assertRealGlobalAncestors(homeDirectory, path.dirname(linkPath), fileSystem);
+    const managedPath = managedProtectionPaths(homeDirectory, options.managedInstallations)
+        .find((protectedPath) => pathsOverlap(pathKey(linkPath), protectedPath));
+    if (managedPath !== undefined) {
+        throw new Error(`Cannot remove ${JSON.stringify(linkPath)} because it is managed or aliases a managed installation at ${JSON.stringify(managedPath)}; no path was changed`);
+    }
+    const information = await fileSystem.lstat(linkPath);
+    if (!information.isSymbolicLink()) {
+        throw new Error(`Selected unmanaged link must be a symbolic link: ${linkPath}; no path was changed`);
+    }
+    return Object.freeze({
+        name: path.basename(linkPath),
+        path: linkPath,
+        target: await readlink(linkPath),
+        identity: fileIdentity(information),
+    });
+}
+/** Rechecks the inspected link (and the managed records when given), then unlinks only the link. */
+export async function removeUserGlobalSymlink(inspection, options) {
+    const unchanged = (current) => current.name === inspection.name && current.path === inspection.path &&
+        current.target === inspection.target && current.identity === inspection.identity;
+    const changed = () => new Error(`The inspected unmanaged link changed before deletion: ${JSON.stringify(inspection.path)}; no path was changed`);
+    if (!unchanged(await inspectUserGlobalSymlinkRemoval(inspection.path, options)))
+        throw changed();
+    if (options.readManagedInstallations !== undefined) {
+        const latest = await options.readManagedInstallations();
+        if (options.expectedManagedInstallations !== undefined && !sameManagedInstallations(options.expectedManagedInstallations, latest)) {
+            throw new Error(`Managed Skill records changed before deleting unmanaged link ${JSON.stringify(inspection.path)}; no path was changed`);
+        }
+        if (!unchanged(await inspectUserGlobalSymlinkRemoval(inspection.path, { ...options, managedInstallations: latest })))
+            throw changed();
+    }
+    // A swap for a real directory is caught by the last recheck above or refused by unlink (EISDIR/EPERM).
+    // A remaining window: the link replaced by another symbolic link between that recheck and this unlink
+    // is still removed, because unlink cannot verify identity atomically. Only a link is ever unlinked.
+    await unlink(inspection.path);
+}
+async function inspectStagedSkill(candidatePath, name, fileSystem) {
+    const information = await realDirectory(candidatePath, "staged unmanaged Skill", fileSystem);
+    const tree = await readUnmanagedTree(candidatePath, name, fileSystem);
+    return {
+        name,
+        path: candidatePath,
+        identity: fileIdentity(information),
+        digest: skillTreeBaseline(tree).digest,
+    };
+}
+async function restoreStagedSkill(stagingPath, targetPath, expected, fileSystem) {
+    try {
+        const staged = await inspectStagedSkill(stagingPath, expected.name, fileSystem);
+        if (staged.identity !== expected.identity || staged.digest !== expected.digest)
+            return false;
+        await fileSystem.rename(stagingPath, targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readUnmanagedTree(candidatePath, skillName, fileSystem) {
+    return readExistingSkillTree(candidatePath, skillName, fileSystem);
+}
+async function realDirectory(candidatePath, label, fileSystem = nodeFileSystem) {
+    const information = await fileSystem.lstat(candidatePath);
+    if (information.isSymbolicLink() || !information.isDirectory()) {
+        throw new Error(`${label} must be a real directory: ${candidatePath}; no path was changed`);
+    }
+    return information;
+}
+async function assertRealGlobalAncestors(homeDirectory, skillRoot, fileSystem) {
+    const relative = path.relative(homeDirectory, skillRoot);
+    if (relative === "" || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`Selected unmanaged Skill has an unsafe global ancestor: ${skillRoot}; no path was changed`);
+    }
+    await realDirectory(homeDirectory, "global home", fileSystem);
+    let current = homeDirectory;
+    for (const segment of relative.split(path.sep)) {
+        current = path.join(current, segment);
+        await realDirectory(current, "global Skill ancestor", fileSystem);
+    }
+}
+function validateExplicitGlobalPath(candidatePath, homeDirectory) {
+    if (!path.isAbsolute(candidatePath) || candidatePath !== path.normalize(candidatePath)) {
+        throw new Error(`Unmanaged Skill removal requires an exact normalized absolute global path: ${JSON.stringify(candidatePath)}; no path was changed`);
+    }
+    const root = GLOBAL_SKILL_ROOTS.find((candidate) => isUnderGlobalRoot(candidatePath, homeDirectory, candidate.kind === "agents" ? ".agents" : ".claude"));
+    if (root === undefined) {
+        throw new Error(`Unmanaged Skill path must be an immediate child under ${path.join(homeDirectory, ".agents", "skills")} or ${path.join(homeDirectory, ".claude", "skills")}: ${candidatePath}; no path was changed`);
+    }
+    if (isTransientName(path.basename(candidatePath))) {
+        throw new Error(`Backup or transient paths are not unmanaged Skill removal candidates: ${candidatePath}; no path was changed`);
+    }
+    return candidatePath;
+}
+function managedProtectionPaths(homeDirectory, selections) {
+    const protectedPaths = new Set();
+    for (const selection of selections) {
+        const installationPath = selection.installation?.path;
+        if (installationPath === undefined)
+            continue;
+        const absolutePath = resolveInstallationPath(homeDirectory, installationPath);
+        if (absolutePath === undefined)
+            continue;
+        for (const alias of globalPathAliases(absolutePath))
+            protectedPaths.add(pathKey(alias));
+    }
+    return [...protectedPaths];
+}
+function globalPathAliases(candidatePath) {
+    const resolved = path.resolve(candidatePath);
+    const aliases = [resolved];
+    if (isGlobalLocation(resolved, ".agents") || isGlobalLocation(resolved, ".claude")) {
+        const rootName = isGlobalLocation(resolved, ".agents") ? ".agents" : ".claude";
+        const otherRoot = rootName === ".agents" ? ".claude" : ".agents";
+        aliases.push(path.join(path.dirname(path.dirname(path.dirname(resolved))), otherRoot, "skills", path.basename(resolved)));
+    }
+    return aliases;
+}
+function isGlobalLocation(candidatePath, rootName) {
+    const skillsPath = path.dirname(candidatePath);
+    const globalRootPath = path.dirname(skillsPath);
+    const expectedRootPath = path.join(path.dirname(globalRootPath), rootName);
+    return pathKey(skillsPath) === pathKey(path.join(globalRootPath, "skills")) &&
+        pathKey(globalRootPath) === pathKey(expectedRootPath);
+}
+function fileIdentity(information) {
+    const native = `${information.dev}:${information.ino}`;
+    if (!information.isSymbolicLink()) {
+        // A directory's content digest covers a replacement that reuses an inode.
+        return native;
+    }
+    // A link has no content to digest and inode numbers are recycled, so add the
+    // birth time and the link size (mirrors pathIdentityKey in project-installation).
+    const birth = Number.isFinite(information.birthtimeMs) && information.birthtimeMs > 0 ? information.birthtimeMs : 0;
+    return `${native}:${information.size}:${birth}`;
+}
+function skip(candidatePath, root, reason, detail, name) {
+    return { ...(name === undefined ? {} : { name }), path: candidatePath, root, reason, detail };
+}
+function resolveInstallationPath(homeDirectory, installationPath) {
+    const normalized = installationPath.replaceAll("\\", "/");
+    if (path.posix.isAbsolute(normalized))
+        return undefined;
+    const absolutePath = path.resolve(homeDirectory, ...normalized.split("/"));
+    const relative = path.relative(homeDirectory, absolutePath);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        return undefined;
+    return absolutePath;
+}
+function isUnderGlobalRoot(candidatePath, homeDirectory, directoryName) {
+    const rootPath = pathKey(path.join(homeDirectory, directoryName, "skills"));
+    const relative = path.relative(rootPath, pathKey(candidatePath));
+    return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative) &&
+        !relative.includes(path.sep);
+}
+function pathKey(candidatePath) {
+    return path.normalize(path.resolve(candidatePath)).toLowerCase();
+}
+function isTransientName(name) {
+    const normalized = name.toLowerCase();
+    return /^\.agent-depot-(?:backup|update|overwrite|stage|staging|temp|tmp)(?:-|$)/u.test(normalized) ||
+        /\.agent-depot-unmanaged-stage-(?:[0-9a-f-]+)$/u.test(normalized) ||
+        normalized.endsWith(".tmp");
+}
+function sameManagedInstallations(left, right) {
+    return left.map((selection) => JSON.stringify(selection)).sort().join("\n") ===
+        right.map((selection) => JSON.stringify(selection)).sort().join("\n");
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/user-method.js

@@ -0,0 +1,14 @@
+import path from "node:path";
+/**
+ * Produces a terminal-independent command preview. This function has no
+ * process or filesystem side effects and is safe to call during assessment.
+ */
+export function previewUserMethod(options) {
+    return Object.freeze({
+        argv: Object.freeze([...options.method.argv]),
+        cwd: path.resolve(options.projectRoot, options.method.cwd ?? "."),
+        target: options.target,
+        declaredChanges: Object.freeze([...options.declaredChanges]),
+        warning: "The external method may have effects Agent Depot cannot verify or roll back.",
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iseoane/agent-depot",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A cross-platform catalog for reusable coding-agent skills.",
   "license": "MIT",
   "author": "iseoane",
@@ -25,7 +25,10 @@
   },
   "files": [
     "dist/src",
+    "!dist/src/**/*.map",
     "skills",
+    "!skills/**/test_*.py",
+    "!skills/**/testdata",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -41,9 +44,9 @@
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
     "typecheck": "tsc --noEmit",
     "lint": "eslint \"src/**/*.{ts,tsx}\" \"tests/**/*.{ts,tsx}\"",
-    "test": "pnpm build && node --test \"dist/tests/*.test.js\"",
-    "test:single": "pnpm build && node -e \"const { spawnSync } = require('node:child_process'); const input = process.argv[1] || 'tests/version.test.ts'; const file = input.replace(/^tests[\\\\/]/, 'dist/tests/').replace(/\\\\.ts$/i, '.js'); process.exit(spawnSync(process.execPath, ['--test', file], { stdio: 'inherit' }).status ?? 1);\"",
-    "test:coverage": "node -e \"require('node:fs').rmSync('coverage',{recursive:true,force:true})\" && tsc -p tsconfig.coverage.json && node -e \"const { spawnSync } = require('node:child_process'); process.exit(spawnSync(process.execPath, ['--enable-source-maps','--test','--test-reporter=dot','dist/tests/*.test.js'], { stdio: 'inherit', env: { ...process.env, NODE_V8_COVERAGE: 'coverage/v8' } }).status ?? 1);\"",
+    "test": "pnpm build && node --test --import ./dist/tests/isolated-env.js \"dist/tests/*.test.js\"",
+    "test:single": "pnpm build && node -e \"const { spawnSync } = require('node:child_process'); const input = process.argv[1] || 'tests/version.test.ts'; const file = input.replace(/^tests[\\\\/]/, 'dist/tests/').replace(/\\\\.ts$/i, '.js'); process.exit(spawnSync(process.execPath, ['--import', './dist/tests/isolated-env.js', '--test', file], { stdio: 'inherit' }).status ?? 1);\"",
+    "test:coverage": "node -e \"require('node:fs').rmSync('coverage',{recursive:true,force:true})\" && tsc -p tsconfig.coverage.json && node -e \"const { spawnSync } = require('node:child_process'); process.exit(spawnSync(process.execPath, ['--enable-source-maps','--import','./dist/tests/isolated-env.js','--test','--test-reporter=dot','dist/tests/*.test.js'], { stdio: 'inherit', env: { ...process.env, NODE_V8_COVERAGE: 'coverage/v8' } }).status ?? 1);\"",
     "audit:dead-code": "npx --yes fallow@3.30.0 dead-code --fail-on-issues",
     "audit:dupes": "npx --yes fallow@3.30.0 dupes",
     "audit:health": "pnpm test:coverage && npx --yes fallow@3.30.0 health --coverage coverage/v8 --min-score 85",

package/skills/agent-depot-apprecipe/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: "agent-depot-apprecipe"
+description: "Trigger: App recipe creation or repair. Research an App's actual install channel and write platform-aware Agent Depot recipes."
+license: MIT
+metadata:
+  author: "iseoane"
+  version: "1.0"
+---
+
+## Activation Contract
+
+Use for creating or repairing user-global App recipes, not portable Skills.
+
+## Hard Rules
+
+- Read `agent-depot app schema` first: it is the format source of truth. Research upstream README, install docs and releases through the web or GitHub API; never clone the App repository.
+- Write user-owned JSON in the environment-local `apps/` beside `sources.json`. Preserve existing files unless the user authorizes replacement. Keep Apps out of Sources and project manifests.
+- Never approve a recipe on the user's behalf. Approval belongs to the user via `agent-depot app approve <name> --yes`; changed bytes need renewed approval. Validation is not approval.
+- Use bare executable-plus-arguments arrays, without shells, shell syntax, credentials or environment assignments. Script-only routes (`curl | sh`, PowerShell scripts, `.cmd`) belong in `manual` text, never pipe-to-shell argv. Agent Depot displays manual text without executing it.
+- Steps run from the user's home with stdin EOF and no timeout. Use non-interactive flags; terminal-dependent installers belong in manual steps.
+
+## Decision Gates
+
+| Evidence | Recipe decision |
+|---|---|
+| Identical steps on all supported platforms | Omit `platform`. |
+| Steps differ by OS or architecture | Use separate files with the same App `name` and explicit `linux`, `windows` or `darwin`; ask about architecture where needed. Never create duplicate applicable names. |
+| Unsupported platform | Report it; invent no steps. WSL is Linux, not Windows. |
+| Several installs or uncertain channel | List every path/channel and ask the user to choose before writing lifecycle steps. |
+| brew / npm / pipx | Derive update and uninstall from that channel: upgrade/uninstall, global install/uninstall, or upgrade/uninstall respectively. |
+| Go install / release binary | Use the documented update route and a manual binary-removal step. |
+| App has its own uninstall | Prefer it after verifying scope and non-interactive flags; explain remaining channel cleanup. |
+
+## Execution Steps
+
+1. Record upstream evidence and platform support. Inspect all PATH matches (`which -a`/`whence -a`, or Windows `Get-Command -All`), resolved paths, and channel inventories such as `brew list`, `npm ls -g` or `pipx list`. List Windows shims seen from WSL separately: `/mnt/<drive>/` executables cannot serve a Linux recipe. Finish only when the actual channel is established or the user has chosen one.
+2. Write required `name`, `install`, `update`, `uninstall`, and `version`. Each lifecycle step uses `argv`, `manual`, or both; manual fallback applies only to spawn failure, never non-zero exit. `version` needs read-only argv and a JavaScript regex with exactly one capture group. Choose optional `latest` as `github: owner/repo`, `npm: package`, or read-only `argv` plus `pattern`; omit it when unknown. Consult [the illustrative example](assets/example.md), not as upstream command evidence.
+3. Put user-global Host wiring in optional `setup`/`teardown` maps keyed by `pi`, `claude`, `codex`, or `opencode`. Keep install separate; uninstall never implicitly runs teardown. Delegate wiring to App commands or manual user instructions, not direct agent edits of Host configuration. Exclude project initialization.
+4. Declare optional `skills` only for documented App-owned directory/link names. Match whole names case-sensitively; only `*` is special, while `?` and brackets are literal. Reject empty/whitespace-only, path separators, NUL and star-only patterns. These declarations filter unmanaged adoption/removal even before approval/install; they verify no artifacts or provenance.
+5. Run `agent-depot app validate <file>...` for current-platform recipes. Fix structural errors; report unapproved recipes as needs approval, not runtime-verified. Version commands run only for approved applicable content. Mark other platforms unverified. After user approval, the user can inspect `app list` and separately preview `app install|update|uninstall <name>` or `app setup|teardown <name> --host <host>`.
+
+## Output Contract
+
+Return file paths, platform/channel evidence, validation results and runtime-verification limits; unsupported platforms; omitted optional fields and why; license, telemetry/update-check behavior (or unknown); and conflicting duplicate install routes, including plugin-marketplace versus setup routes. Explain that version alone determines installed state, updates require a changed version, and unknown latest is not an available update. End with the user's approval command, without running it.