@iseoane/agent-depot 0.2.1 → 0.4.0

package/dist/src/profile-export.js

@@ -0,0 +1,135 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { loadAppOwnedSkillFilter } from "./app-owned-skills.js";
+import { sourceIdForUrl } from "./git-source.js";
+import { AGENT_DEPOT_PACKAGE_VERSION } from "./project-manifest.js";
+import { parseProfile, PROFILE_FORMAT, serializeProfile } from "./profile.js";
+import { scanUserGlobalSkillInventory } from "./user-global-skill-inventory.js";
+export function selectProfileItems(items, requested, disabled, names, block) {
+    if (disabled && requested?.length)
+        throw new Error(`${block}: filters cannot be combined with --no-${block}`);
+    for (const name of requested ?? []) {
+        if (!items.some(item => names(item).includes(name)))
+            throw new Error(`${block}: unknown selection ${JSON.stringify(name)}`);
+    }
+    return disabled ? [] : items.filter(item => !requested?.length || names(item).some(name => requested.includes(name)));
+}
+function validateOne(block, item) {
+    const profile = parseProfile({ format: PROFILE_FORMAT, agentDepotVersion: AGENT_DEPOT_PACKAGE_VERSION,
+        sources: [], skills: [], apps: [], [block]: [item] });
+    return profile[block][0];
+}
+/** Read-only export plan shared by terminal frontends; never refreshes Sources or executes recipes. */
+export async function buildProfileExport(operations, apps, options = {}) {
+    if (!operations.listUserGlobalInstallations)
+        throw new Error("Profile export requires user-global installation listing");
+    if (!AGENT_DEPOT_PACKAGE_VERSION)
+        throw new Error("Unable to determine the Agent Depot package version");
+    const diagnostics = [];
+    const exclude = (block, label, reason) => {
+        diagnostics.push({ block, label, reason });
+    };
+    const warn = (message) => diagnostics.push({ kind: "load", message });
+    const sources = selectProfileItems(await operations.listSources(), options.sources, options.noSources, source => source.kind === "git" ? [source.id, source.url] : [source.id], "sources");
+    const allInstallations = await operations.listUserGlobalInstallations();
+    const installations = selectProfileItems(allInstallations, options.skills, options.noSkills, skill => [skill.path, path.posix.basename(skill.path)], "skills");
+    const entries = selectProfileItems(await apps.load(), options.apps, options.noApps, entry => [entry.recipe?.name ?? path.basename(entry.file)], "apps");
+    const owned = await loadAppOwnedSkillFilter({ appEnvironment: { recipesDirectory: apps.directory },
+        reportWarning: warn });
+    const portableSources = [];
+    for (const source of sources) {
+        if (source.kind === "builtin") {
+            exclude("sources", "built-in Source", "always present (built-in Skill selections remain portable)");
+            continue;
+        }
+        try {
+            portableSources.push(validateOne("sources", {
+                url: source.url, included: options.includedSourceIds?.includes(source.id) ?? true,
+            }));
+        }
+        catch (error) {
+            exclude("sources", `Source ${source.id}`, `local-path or invalid Source, not portable (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    const skills = [];
+    for (const skill of installations) {
+        if (owned(path.posix.basename(skill.installation?.path ?? skill.path))) {
+            exclude("skills", `Skill ${skill.path}`, "App-owned");
+            continue;
+        }
+        const { source, path: skillPath, version, hosts, methods } = skill;
+        const selection = { source, path: skillPath, version, hosts, ...(methods ? { methods } : {}) };
+        try {
+            skills.push(validateOne("skills", selection));
+            if (skill.installation)
+                exclude("skills", `installation location and version evidence for Skill ${skill.path}`, "machine-specific");
+        }
+        catch (error) {
+            exclude("skills", `Skill ${skill.path}`, `not portable (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    const recipes = [];
+    for (const entry of entries) {
+        try {
+            if (entry.error)
+                throw new Error(entry.error);
+            recipes.push(validateOne("apps", entry.recipe));
+        }
+        catch (error) {
+            exclude("apps", `App recipe ${path.basename(entry.file)}`, error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (!options.noSkills) {
+        const inventory = await scanUserGlobalSkillInventory({
+            homeDirectory: options.homeDirectory, managedInstallations: allInstallations,
+            appEnvironment: { recipesDirectory: apps.directory }, reportWarning: warn,
+        });
+        for (const name of new Set([...inventory.unmanaged, ...inventory.symlinks].map(skill => skill.name))) {
+            exclude("skills", `unmanaged Skill ${name}`, "not tracked");
+        }
+    }
+    const profile = parseProfile({ format: PROFILE_FORMAT, agentDepotVersion: AGENT_DEPOT_PACKAGE_VERSION,
+        sources: portableSources, skills, apps: recipes });
+    return {
+        profile,
+        exclusions: diagnostics.filter((item) => "block" in item),
+        warnings: [...diagnostics.filter((item) => "kind" in item), ...sourceWarnings(profile)],
+        preview: profileExportPreview(profile, diagnostics),
+    };
+}
+function sourceWarnings(profile) {
+    return profile.skills.flatMap(skill => {
+        const identity = skill.source;
+        if (identity.kind === "external" && "url" in identity && !profile.sources.some(source => source.url === identity.url)) {
+            return [{ kind: "source", message: `WARNING: Skill ${skill.path} references Source ${identity.url} not included in profile` }];
+        }
+        return [];
+    });
+}
+/** Shared preview for a frontend-selected subset; Source warnings are recomputed. */
+export function profileExportPreview(profile, diagnostics = []) {
+    return ["Preview: export portable user-global profile",
+        ...profile.sources.map(source => `Source ${sourceIdForUrl(source.url)} ${source.url} (included: ${source.included})`),
+        ...profile.skills.map(skill => `Skill ${skill.path} [${skill.hosts.join(", ")}] (${skill.version.policy})`),
+        ...profile.apps.map(recipe => `App recipe ${recipe.name} (${recipe.platform ?? "all platforms"}; no approval)`),
+        ...diagnostics.flatMap(item => "block" in item ? [`Excluded ${item.label}: ${item.reason}`] : item.kind === "load" ? [item.message] : []),
+        ...sourceWarnings(profile).map(warning => warning.message)];
+}
+/** Empty profiles are valid to parse, but are not useful export artifacts. */
+export function requireProfileExportSelection(profile) {
+    if (!profile.sources.length && !profile.skills.length && !profile.apps.length) {
+        throw new Error("Nothing selected; nothing written.");
+    }
+}
+/** Exclusively create an export artifact; never replace a file or follow a symlink. */
+export async function writeProfileExport(file, profile) {
+    requireProfileExportSelection(profile);
+    try {
+        await writeFile(file, serializeProfile(profile), { encoding: "utf8", flag: "wx" });
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw new Error(`${file} already exists; choose another path`);
+        throw error;
+    }
+}

package/dist/src/profile-import.js

@@ -0,0 +1,218 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { compareAppVersions } from "./app-version.js";
+import { canonicalizeGitSourceUrl, sourceIdForUrl } from "./git-source.js";
+import { selectProfileItems } from "./profile-export.js";
+import { parseProfile, PROFILE_FORMAT } from "./profile.js";
+import { AGENT_DEPOT_PACKAGE_VERSION } from "./project-manifest.js";
+import { defaultProjectSkillTreeAccess, executeSingleInstall, formatVersionPolicy, outputSingleInstallPreview, planSingleInstall } from "./skill-install.js";
+import { resolveProjectSource } from "./sources.js";
+// Compare declarations, not installation evidence or JSON object insertion order.
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
+    return JSON.stringify(value) ?? "null";
+}
+function skillIdentity(skill) {
+    const source = skill.source;
+    return canonical([source.kind === "external" && "url" in source
+            ? { ...source, url: canonicalizeGitSourceUrl(source.url) } : source, skill.path]);
+}
+function skillChoices(skill) {
+    return { hosts: [...skill.hosts].sort(), version: skill.version, methods: skill.methods };
+}
+function recipeIdentity(recipe) {
+    return canonical([recipe.name, recipe.platform]);
+}
+function fieldDifferences(existing, incoming) {
+    const left = new Map(Object.entries(existing)), right = new Map(Object.entries(incoming));
+    return [...new Set([...left.keys(), ...right.keys()])].sort().flatMap(key => canonical(left.get(key)) === canonical(right.get(key)) ? []
+        : [`${key}: existing ${canonical(left.get(key))} -> incoming ${canonical(right.get(key))}`]);
+}
+function comparison(existing, incoming) {
+    if (existing === undefined)
+        return { status: "add" };
+    const differences = fieldDifferences(existing, incoming);
+    return differences.length ? { status: "conflict", difference: differences.join("; ") } : { status: "same" };
+}
+async function loadImportRecipes(apps) {
+    const entries = await apps.load();
+    return Promise.all(entries.map(async (entry) => {
+        let content = entry.recipe;
+        let error = entry.error;
+        let name = entry.recipe?.name;
+        let platform = entry.recipe?.platform;
+        if (!content) {
+            try {
+                const raw = JSON.parse(await readFile(entry.file, "utf8"));
+                if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+                    content = raw;
+                    const rawName = raw.name;
+                    if (typeof rawName === "string")
+                        name = rawName;
+                    platform = raw.platform;
+                }
+            }
+            catch (cause) {
+                const reason = cause instanceof Error ? cause.message : String(cause);
+                error = `${entry.error && entry.error !== reason ? `${entry.error}; ` : ""}raw JSON read/parse failed: ${reason}`;
+            }
+        }
+        return { file: entry.file, name, platform, content, error };
+    }));
+}
+function classifySource(value, sources) {
+    const exists = sources.some(source => source.kind === "git" && canonicalizeGitSourceUrl(source.url) === value.url);
+    return { block: "sources", value, label: `Source ${value.url} (included: ${value.included})`, status: exists ? "same" : "add",
+        ...(exists && !value.included ? { difference: "included: existing true -> incoming false (discovery inclusion is not imported)" } : {}) };
+}
+function classifySkill(value, skills) {
+    const existing = skills.find(skill => skillIdentity(skill) === skillIdentity(value));
+    return { block: "skills", value, label: `Skill ${value.path}`, ...comparison(existing && skillChoices(existing), skillChoices(value)) };
+}
+function classifyRecipe(value, recipes) {
+    const existing = recipes.filter(entry => entry.name === value.name &&
+        (entry.platform === undefined || value.platform === undefined || entry.platform === value.platform));
+    if (existing.length === 1 && !existing[0].error &&
+        existing[0].platform === value.platform &&
+        fieldDifferences(existing[0].content ?? {}, value).length === 0) {
+        return { block: "apps", value, label: `App recipe ${value.name} (${value.platform ?? "all platforms"}; unapproved; Apps are not installed)`, status: "same" };
+    }
+    return { block: "apps", value, label: `App recipe ${value.name} (${value.platform ?? "all platforms"}; unapproved; Apps are not installed)`,
+        status: existing.length ? "conflict" : "add",
+        ...(existing.length ? { difference: existing.map(entry => `${entry.file}: name ${JSON.stringify(value.name)} already present with overlapping platforms; ${fieldDifferences(entry.content ?? {}, value).join("; ") || "content identical"}`).join("; ") } : {}) };
+}
+/** Load only this block; retained across skips and invalidated after every attempted write. */
+async function loadImportClassifier(block, operations, apps) {
+    if (block === "sources") {
+        const sources = await operations.listSources();
+        return (item) => item.block === "sources" ? classifySource(item.value, sources) : item;
+    }
+    if (block === "skills") {
+        if (!operations.listUserGlobalInstallations)
+            throw new Error("Profile import requires user-global installation listing");
+        const skills = await operations.listUserGlobalInstallations();
+        return (item) => item.block === "skills" ? classifySkill(item.value, skills) : item;
+    }
+    const recipes = await loadImportRecipes(apps);
+    return (item) => item.block === "apps" ? classifyRecipe(item.value, recipes) : item;
+}
+/** Read-only classification. Inclusion is a transient frontend choice, not persisted Source state. */
+export async function buildProfileImport(input, operations, apps, filters = {}) {
+    const profile = parseProfile(input);
+    if (!operations.listUserGlobalInstallations)
+        throw new Error("Profile import requires user-global installation listing");
+    const sources = await operations.listSources();
+    const skills = await operations.listUserGlobalInstallations();
+    const recipes = await loadImportRecipes(apps);
+    const items = [];
+    for (const value of selectProfileItems(profile.sources, filters.sources, filters.noSources, source => [source.url, sourceIdForUrl(source.url)], "sources"))
+        items.push(classifySource(value, sources));
+    for (const value of selectProfileItems(profile.skills, filters.skills, filters.noSkills, skill => [skill.path, path.posix.basename(skill.path)], "skills"))
+        items.push(classifySkill(value, skills));
+    for (const value of selectProfileItems(profile.apps, filters.apps, filters.noApps, recipe => [recipe.name], "apps")) {
+        items.push(classifyRecipe(value, recipes));
+    }
+    const preview = ["Preview: import portable user-global profile", ...items.flatMap(item => {
+            const status = item.block === "sources" && item.status === "same" && !item.value.included
+                ? "same (discovery inclusion is not imported)" : item.status;
+            const lines = [`${status}: ${item.label}${item.difference ? `; ${item.difference}` : ""}`];
+            if (item.block === "skills" && item.status === "add") {
+                const skill = item.value;
+                lines.push(`  Source ${canonical(skill.source)}`, `  hosts: ${skill.hosts.join(",")}; version policy: ${formatVersionPolicy(skill.version)}`);
+                for (const [action, method] of Object.entries(skill.methods ?? {})) {
+                    lines.push(`  ${action}: argv=${JSON.stringify(method.argv)} (user-provided method from the profile, runs only after --yes)`);
+                }
+                const source = skill.source;
+                if (source.kind === "external" && "url" in source &&
+                    !sources.some(registered => registered.kind === "git" && canonicalizeGitSourceUrl(registered.url) === canonicalizeGitSourceUrl(source.url)) &&
+                    !items.some(candidate => candidate.block === "sources" && canonicalizeGitSourceUrl(candidate.value.url) === canonicalizeGitSourceUrl(source.url) && candidate.status === "add")) {
+                    lines.push(`  Source ${source.url} will be fetched but not registered`);
+                }
+            }
+            return lines;
+        })];
+    preview.push(...recipes.filter(entry => entry.error).map(entry => `WARNING: ${entry.file}: ${entry.error}${entry.name === undefined ? "; name unknown; unrelated names are not blocked" : ""}`));
+    if (AGENT_DEPOT_PACKAGE_VERSION && (compareAppVersions(profile.agentDepotVersion, AGENT_DEPOT_PACKAGE_VERSION) ?? 0) > 0) {
+        preview.push(`WARNING: profile Agent Depot ${profile.agentDepotVersion} is newer than running ${AGENT_DEPOT_PACKAGE_VERSION}`);
+    }
+    preview.push("Existing choices are never replaced. Source inclusion is a transient discovery choice.", "Same-name App recipes conflict only when platforms overlap; disjoint platform recipes can both be added.");
+    return { items, preview };
+}
+/** Publish complete JSON exclusively: rename would silently overwrite an existing recipe. */
+async function writeRecipe(directory, recipe) {
+    await mkdir(directory, { recursive: true });
+    // A new canonical path cannot inherit a receipt left by a deleted recipe.
+    const filename = `profile-${createHash("sha256").update(recipeIdentity(recipe)).digest("hex")}-${randomUUID()}.json`;
+    const destination = path.join(directory, filename);
+    const temporary = path.join(directory, `.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, `${JSON.stringify(recipe, null, 2)}\n`, { flag: "wx" });
+        await link(temporary, destination);
+    }
+    finally {
+        await unlink(temporary).catch(error => { if (error.code !== "ENOENT")
+            throw error; });
+    }
+}
+/** Apply only confirmed additions, rechecking destination choices per item. Failures remain independent. */
+export async function applyProfileImport(plan, operations, apps, confirmed, output, environment = {}) {
+    const results = [];
+    for (const block of ["sources", "skills", "apps"]) {
+        let classify;
+        for (const item of plan.items.filter(item => item.block === block)) {
+            if (!confirmed || item.status !== "add") {
+                results.push({ item, status: "skipped" });
+                continue;
+            }
+            try {
+                parseProfile({ format: PROFILE_FORMAT, agentDepotVersion: AGENT_DEPOT_PACKAGE_VERSION,
+                    sources: [], skills: [], apps: [], [block]: [item.value] });
+                classify ??= await loadImportClassifier(block, operations, apps);
+                const recheck = classify(item);
+                if (recheck.status !== "add") {
+                    results.push({ item, status: "skipped", detail: `${recheck.status}: ${recheck.label}${recheck.difference ? `; ${recheck.difference}` : ""}` });
+                    continue;
+                }
+                // Even a failing install method can persist state or change recipe files.
+                classify = undefined;
+                if (item.block === "sources")
+                    await operations.addGitSource(item.value.url);
+                else if (item.block === "apps")
+                    await writeRecipe(apps.directory, item.value);
+                else {
+                    await installImportedSkill(item.value, operations, apps, output, environment);
+                }
+                results.push({ item, status: "added" });
+            }
+            catch (error) {
+                results.push({ item, status: "failed", detail: error instanceof Error ? error.message : String(error) });
+            }
+        }
+    }
+    return results;
+}
+async function installImportedSkill(selection, operations, apps, output, environment) {
+    if (!operations.addUserGlobalInstallation || !operations.listUserGlobalInstallations)
+        throw new Error("Cannot persist user-global Skills");
+    const source = selection.source;
+    // A Skill's Source identity is self-contained even when its Source block was filtered out.
+    const resolvedSource = await (operations.resolveProjectSource ? operations.resolveProjectSource(source) : resolveProjectSource(source));
+    const install = await planSingleInstall({ scope: "user-global", sourceId: resolvedSource.id, skillPath: selection.path,
+        version: selection.version, hosts: selection.hosts, ref: source.kind === "external" ? source.ref : undefined,
+        method: selection.methods?.install, portableV1: true, confirmed: true, overwrite: false, confirmAdditionalHostExposure: false }, { operations: { ...operations, listSources: async () => [resolvedSource] }, sourceAccess: operations.readSkillTreeSnapshot ? {
+            readSkillTree: async (source, skillPath) => (await operations.readSkillTreeSnapshot(source, skillPath)).files,
+            readSkillTreeSnapshot: (source, skillPath) => operations.readSkillTreeSnapshot(source, skillPath),
+        } : defaultProjectSkillTreeAccess(),
+        environment: { ...environment, appEnvironment: { recipesDirectory: apps.directory } }, root: path.resolve(environment.homeDirectory ?? homedir()),
+        existing: await operations.listUserGlobalInstallations(), recordedIn: "user-global state" });
+    // Preserve both user methods and the exact recorded Source ref/version choices.
+    const exactPlan = { ...install, selection, resolved: { ...install.resolved, selection } };
+    outputSingleInstallPreview(exactPlan, output);
+    await executeSingleInstall(exactPlan, record => operations.addUserGlobalInstallation(record), output);
+}

package/dist/src/profile.js

@@ -0,0 +1,130 @@
+import path from "node:path";
+import { parseAppRecipe } from "./app-recipes.js";
+import { canonicalizeGitSourceUrl } from "./git-source.js";
+import { containsCredentialArgument, parseProjectManifest, ProjectManifestError } from "./project-manifest.js";
+export const PROFILE_FORMAT = "agent-depot-profile/v1";
+function object(value, keys, field) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${field}: expected an object`);
+    const record = value;
+    const extra = Object.keys(record).find(key => !keys.includes(key));
+    if (extra !== undefined)
+        throw new Error(`${field}.${extra}: unsupported profile field`);
+    return record;
+}
+function list(value, field) {
+    if (!Array.isArray(value))
+        throw new Error(`${field}: expected an array`);
+    return value;
+}
+/** Recipes can contain free text; portable profiles additionally forbid machine paths and credentials. */
+function assertPortableText(value, field) {
+    if (typeof value === "string") {
+        const commandPath = /(?:\.argv\[\d+\]|\.cwd)$/u.test(field) &&
+            (path.posix.isAbsolute(value) || path.win32.isAbsolute(value));
+        const regexPattern = /\.(?:version|latest)\.pattern$/u.test(field);
+        if (commandPath || (!regexPattern && /(?:^|[\s="'(])(?:\/(?!\/)[\w.]|[A-Za-z]:[/\\]|\\\\)/u.test(value))) {
+            throw new Error(`${field}: absolute local paths are not portable`);
+        }
+        if (/[a-z][a-z0-9+.-]*:\/\/[^\s/]*@/iu.test(value)) {
+            throw new Error(`${field}: credentials are not portable`);
+        }
+        for (const match of value.matchAll(/[a-z][a-z0-9+.-]*:\/\/[^\s"'<>]+/giu)) {
+            let url;
+            try {
+                url = new URL(match[0]);
+            }
+            catch {
+                throw new Error(`${field}: invalid URL`);
+            }
+            const keys = [...url.searchParams.keys(), ...new URLSearchParams(url.hash.slice(1)).keys()];
+            if (keys.some(key => /^(?:token|key|apikey|secret|password|passwd|auth|sig|signature|accesstoken|privatetoken)$/u.test(key.replace(/[-_]/gu, "").toLowerCase()))) {
+                throw new Error(`${field}: credentials are not portable`);
+            }
+        }
+        // Manual text is not argv: check credentials without forbidding its shell instructions.
+        if (containsCredentialArgument(value) || value.split(/\s+/u).some(containsCredentialArgument)) {
+            throw new Error(`${field}: credentials are not portable`);
+        }
+    }
+    else if (Array.isArray(value)) {
+        value.forEach((item, index) => assertPortableText(item, `${field}[${index}]`));
+    }
+    else if (value && typeof value === "object") {
+        for (const [key, item] of Object.entries(value))
+            assertPortableText(item, `${field}.${key}`);
+    }
+}
+function rejectDuplicates(items, identity, field) {
+    const seen = new Set();
+    items.forEach((item, index) => {
+        const key = identity(item);
+        if (seen.has(key))
+            throw new Error(`${field}[${index}]: duplicate identity`);
+        seen.add(key);
+    });
+}
+/** Portable profile parsing shares the manifest and recipe safety contracts. */
+export function parseProfile(value) {
+    const root = object(value, ["format", "agentDepotVersion", "sources", "skills", "apps"], "profile");
+    if (root.format !== PROFILE_FORMAT)
+        throw new Error("profile.format: unsupported profile version");
+    if (typeof root.agentDepotVersion !== "string" || !/^\d+\.\d+\.\d+(?:[-+][\w.+-]+)?$/u.test(root.agentDepotVersion)) {
+        throw new Error("profile.agentDepotVersion: expected a package version");
+    }
+    const sources = list(root.sources, "sources").map((value, index) => {
+        const field = `sources[${index}]`;
+        const source = object(value, ["url", "included"], field);
+        if (typeof source.included !== "boolean")
+            throw new Error(`${field}.included: expected a boolean`);
+        try {
+            return { url: canonicalizeGitSourceUrl(source.url), included: source.included };
+        }
+        catch (error) {
+            throw new Error(`${field}.url: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+    const skills = list(root.skills, "skills");
+    skills.forEach((value, index) => object(value, ["source", "path", "version", "hosts", "methods"], `skills[${index}]`));
+    let parsedSkills;
+    try {
+        parsedSkills = parseProjectManifest({ version: 1, skills }, "profile").skills;
+    }
+    catch (error) {
+        if (!(error instanceof ProjectManifestError))
+            throw error;
+        const [field, ...reason] = error.reason.split(" ");
+        throw new Error(`${field}: ${reason.join(" ")}`);
+    }
+    parsedSkills.forEach((skill, index) => {
+        assertPortableText(skill.path, `skills[${index}].path`);
+        assertPortableText(skill.version, `skills[${index}].version`);
+        assertPortableText(skill.methods, `skills[${index}].methods`);
+    });
+    const apps = list(root.apps, "apps").map((value, index) => {
+        try {
+            const recipe = parseAppRecipe(value);
+            assertPortableText(recipe, `apps[${index}]`);
+            return recipe;
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(reason.startsWith(`apps[${index}]`) ? reason : `apps[${index}].${reason}`);
+        }
+    });
+    rejectDuplicates(sources, source => source.url, "sources");
+    apps.forEach((app, index) => {
+        if (apps.slice(0, index).some(previous => previous.name === app.name &&
+            (previous.platform === undefined || app.platform === undefined || previous.platform === app.platform))) {
+            throw new Error(`apps[${index}]: duplicate applicable App name ${JSON.stringify(app.name)}`);
+        }
+    });
+    const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+    sources.sort((a, b) => compare(a.url, b.url));
+    const sortedSkills = [...parsedSkills].sort((a, b) => compare(JSON.stringify([a.source, a.path]), JSON.stringify([b.source, b.path])));
+    apps.sort((a, b) => compare(a.name, b.name) || compare(a.platform ?? "", b.platform ?? ""));
+    return { format: PROFILE_FORMAT, agentDepotVersion: root.agentDepotVersion, sources, skills: sortedSkills, apps };
+}
+export function serializeProfile(profile) {
+    return `${JSON.stringify(parseProfile(profile), null, 2)}\n`;
+}

package/dist/src/project-manifest.js

@@ -16,10 +16,12 @@ const EMPTY_PROJECT_MANIFEST = Object.freeze({
 });
 export class ProjectManifestError extends Error {
     manifestPath;
+    reason;
     constructor(manifestPath, reason) {
         super(`Invalid project manifest ${JSON.stringify(manifestPath)}: ${reason}`);
         this.name = "ProjectManifestError";
         this.manifestPath = manifestPath;
+        this.reason = reason;
     }
 }
 function isRecord(value) {
@@ -135,6 +137,10 @@ function isShellInterpreter(executable) {
         "cmd", "cmd.exe", "command.com", "powershell", "powershell.exe", "pwsh", "pwsh.exe",
     ]).has(normalized);
 }
+/** Shared conservative credential check for portable declarations, including recipe free text. */
+export function containsCredentialArgument(value) {
+    return CREDENTIAL_FLAG.test(value) || containsObviousCredential(value);
+}
 function containsObviousCredential(value) {
     return /^[A-Za-z_][A-Za-z0-9_]*=.+$/u.test(value) ||
         /(?:^|[=:])[A-Za-z_][A-Za-z0-9_]*=.+/u.test(value) ||

package/dist/src/skill-install.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { assertSkillNotAppOwned } from "./app-owned-skills.js";
 import { pathsOverlap } from "./path-safety.js";
 import { inspectProjectSkillInstallation, installProjectSkillTransaction, validateProjectSkillInstallationPreview, } from "./project-installation.js";
 import { AGENT_DEPOT_PACKAGE_VERSION, parseProjectManifest, } from "./project-manifest.js";
@@ -311,6 +312,7 @@ export async function planSingleInstall(request, context) {
         throw new CliUsageError(`Skill selection ${JSON.stringify(selection.path)} is already recorded in ${context.recordedIn}; already managed Skills must be changed with update apply`);
     }
     const { resolvedSource, resolved, installationInspection } = await resolveInstallInspection(selection, source, projectSource, context.root, request, context.operations, context.environment, context.sourceAccess);
+    await assertInstallNotAppOwned(request, context, installationInspection);
     return { request, context, selection, source, resolvedSource, resolved, inspection: installationInspection };
 }
 /** Prints the preview the user confirms before {@link executeSingleInstall}. */
@@ -324,6 +326,7 @@ export function outputSingleInstallPreview(plan, output) {
  */
 export async function executeSingleInstall(plan, persist, output) {
     const { request, context, selection, resolvedSource, resolved, inspection } = plan;
+    await assertInstallNotAppOwned(request, context, inspection);
     const protectedPaths = assertNoManagedInstallationOverlap(context.existing, selection, inspection, context.root, request.overwrite);
     rejectInstallationCollision(inspection, request.overwrite);
     const transaction = await installOne(selection, resolvedSource, context.sourceAccess, context.root, context.environment, resolved.method, request.portableV1, resolved.files, resolved.resolvedVersion, request.confirmAdditionalHostExposure, request.overwrite, inspection, protectedPaths);
@@ -360,3 +363,12 @@ export function needsAdditionalHostExposure(inspection, hosts) {
     const missingCanonical = hosts.some((host) => host !== "claude") && !identical.includes(inspection.canonicalPath);
     return missingClaude || missingCanonical;
 }
+async function assertInstallNotAppOwned(request, context, inspection) {
+    if (request.scope !== "user-global")
+        return;
+    for (const location of inspection.locations) {
+        if (location.status === "missing")
+            continue;
+        await assertSkillNotAppOwned(path.basename(location.path), { ...context.environment, homeDirectory: context.root });
+    }
+}

package/dist/src/source-state.js

@@ -1,8 +1,8 @@
-import { mkdir, readFile, rename, rmdir, unlink, writeFile } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rmdir, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { setTimeout as delay } from "node:timers/promises";
 import path from "node:path";
+import { writeFileAtomically } from "./atomic-file.js";
 import { canonicalizeGitSourceUrl, sourceIdForUrl } from "./git-source.js";
 import { parseProjectManifest } from "./project-manifest.js";
 const EMPTY_STATE = Object.freeze({
@@ -204,28 +204,7 @@ export class SourceStateStore {
         const normalized = parseState(state, this.path);
         await mkdir(path.dirname(this.path), { recursive: true });
         const contents = `${JSON.stringify(normalized, null, 2)}\n`;
-        const temporaryPath = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
-        try {
-            await writeFile(temporaryPath, contents, { encoding: "utf8", flag: "wx" });
-            try {
-                await rename(temporaryPath, this.path);
-            }
-            catch (error) {
-                if (!isWindowsReplaceError(error)) {
-                    throw error;
-                }
-                // Windows may not replace an existing file with rename. The lock makes
-                // this fallback safe from concurrent read-modify-write operations.
-                await writeFile(this.path, contents, "utf8");
-            }
-        }
-        finally {
-            await unlink(temporaryPath).catch((error) => {
-                if (!isMissingFile(error)) {
-                    throw error;
-                }
-            });
-        }
+        await writeFileAtomically(this.path, contents, { allowLockedReplaceFallback: true });
     }
     async acquireLock() {
         const lockPath = `${this.path}.lock`;
@@ -259,7 +238,3 @@ function isMissingFile(error) {
 function isAlreadyExists(error) {
     return errorCode(error) === "EEXIST";
 }
-function isWindowsReplaceError(error) {
-    const code = errorCode(error);
-    return code === "EEXIST" || code === "EPERM" || code === "ENOTEMPTY";
-}