@iseoane/agent-depot 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-10-01
+
+### Added
+
+- **Profiles**: a portable, versioned `agent-depot-profile/v1` JSON file to carry a user-global setup to another Agent Depot installation (ADR 0008). It holds Git Sources, user-global Skill selections (Source, path, version policy, Hosts, methods) and App recipe contents, plus the producing `agentDepotVersion`. Local-path and built-in Sources, unmanaged and App-owned Skills, approvals and installed state are never exported; credentials in URLs and absolute paths are rejected, and output is canonically ordered.
+- `agent-depot export [--out <file>]` with `--no-sources`, `--no-skills`, `--no-apps` and repeatable `--source`, `--skill`, `--app`; refuses an existing output file and an empty selection.
+- `agent-depot import <file> [--yes]`: an add-only plan (add / same / conflict with per-field differences) that never removes or changes anything present. Without `--yes` nothing is written and every Skill's Hosts, version policy and method argv are shown. Imported App recipes arrive unapproved and Apps are never installed; a recipe conflicts only with a same-name recipe whose platform overlaps.
+- TUI: a fifth tab **5 Import/Export** with checklists for both directions, previews, y/n confirmation and per-item results.
+- TUI: an **App recipes** section in Sources (`Tab` to switch) lists every recipe with its status (approved, needs approval, invalid, not applicable), previews and approves it with Enter, and `n` shows how to add one: install the `agent-depot-apprecipe` skill from the TUI and paste the suggested prompt, or write the recipe by hand in the shown `apps/` directory.
+
 ## [0.3.0] - 2026-10-01
 
 ### Added

package/README.md

@@ -380,7 +380,7 @@ agent-depot tui
 The TUI is an [Ink](https://github.com/vadimdemedes/ink) (React for terminals)
 front end over the same operations as the CLI. It needs Node.js >= 24 and an
 interactive terminal; otherwise `tui` fails with an error. Switch views with
-`1`-`4`, quit with `q` (not while a prompt is open). Every list scrolls when it is
+`1`-`5`, quit with `q` (not while a prompt is open). Every list scrolls when it is
 taller than the terminal. `j`/`k` or the arrow keys move.
 
 | View | Purpose |
@@ -389,6 +389,7 @@ taller than the terminal. `j`/`k` or the arrow keys move.
 | 2 Catalog | Skills that can be installed: those not installed yet, as Source, then Skills. |
 | 3 Installations | What is on disk: managed installations (user-global and project) and unmanaged user-global skills. |
 | 4 Updates | Managed skills with a newer version available, for user-global and project scope. |
+| 5 Import/Export | Transfer portable user-global Source choices, Skill selections and App recipes. |
 
 Keys per view (prompts also accept `Esc` to cancel and `y`/`n` to confirm):
 
@@ -399,6 +400,8 @@ Keys per view (prompts also accept `Esc` to cancel and `y`/`n` to confirm):
 | Installations | `Enter`/arrows expand and collapse, `u` uninstall (all Hosts or chosen Hosts) or remove an unmanaged skill, `h` or `i` add Hosts to an installation, `A` or `Enter` adopt an unmanaged skill, `space` marks a leaf and `a` marks all visible leaves: with marks, `u` and `h` act on all of them with one combined preview and one confirmation (project installations are skipped with a reason) |
 | Updates | `space` mark, `a` mark all, `t`/`p`/`g` show all, project or user-global, `Enter` preview the marks, `r` check again, arrows fold the "cannot assess" line |
 
+| Import/Export | `e` export, `i` import; enter a file path, `space` toggle choices, `a` toggle all, `Enter` preview, `y` apply; `j`/`k` scroll previews and results |
+
 Safety model:
 
 - Nothing is written before a preview and an explicit `y`. Exposing a skill to an
@@ -577,3 +580,76 @@ are previewed before execution; each Host gets an outcome and failures do not st
 remaining Hosts. For manual completion, rerun the selected Host with
 `--manual-done --yes`. This checks the App version, not Host wiring. Host actions
 never change installed-App tracking.
+
+## Export a user-global Profile
+
+Export portable choices to another machine or keep them in git:
+
+```sh
+agent-depot export > profile.json
+agent-depot export --out profile.json
+agent-depot export --no-apps --source <source-id> --skill doctor-md-agents
+agent-depot export --no-sources --no-skills --app my-tool --app another-tool
+```
+
+Everything portable is selected by default. `--no-sources`, `--no-skills` and
+`--no-apps` exclude blocks; repeatable `--source <id|url>`, `--skill <path|name>`
+and `--app <name>` restrict each block independently. Unknown selections and
+combining a block's inclusion filter with its `--no-*` flag are errors.
+
+Stdout contains JSON only; stderr shows the preview and exclusion reasons.
+`--out` requires a new file (existing files and symlinks are not replaced).
+Profiles contain canonical Git URLs with discovery inclusion, recorded Skill
+version policies/Hosts/user methods, and complete App recipes, including recipes
+for other platforms. CLI export always writes `included: true`; discovery choices are transient, while
+the TUI may pass explicit inclusion choices to the shared export core.
+Export neither refreshes Sources nor runs App commands.
+
+Local paths and obvious credentials are not portable. Nonportable/invalid items
+are excluded with reasons, as are unmanaged/App-owned and project Skills,
+installation locations/evidence, approval receipts, installed-App state and
+pending updates. Free-text recipe portability checks are conservative; review
+profiles before sharing them—arbitrary secrets cannot be detected automatically.
+
+## Import a user-global Profile
+
+Preview first, then explicitly confirm the same selection:
+
+```sh
+agent-depot import profile.json
+agent-depot import profile.json --yes
+agent-depot import profile.json --no-apps --skill doctor-md-agents --yes
+```
+
+Import uses the same independent block/name filters as export. It reports **add**,
+**same** (skipped), and **conflict** (difference shown, skipped). Without `--yes`,
+nothing is written. Existing choices and conflicting files are never replaced.
+A profile produced by a newer Agent Depot version gives a warning, not an error.
+
+Confirmed additions run in order: Source registration, user-global Skills through
+normal refreshed install previews and safety checks, then App recipes. Recorded
+Hosts, version policies and user methods are retained. Even without `--yes`,
+each add-Skill preview shows its Source, Hosts, version policy and full argv for
+every user-provided method, marked as running only after confirmation. The normal
+install preview still appears before execution. Each failure is reported independently and remaining items
+continue; any failed item makes the command exit non-zero.
+
+Recipes, including those for other platforms, arrive **unapproved** in `apps/`.
+A same-name destination recipe blocks import only when its platform overlaps the
+incoming recipe: equal platforms overlap, and a missing platform overlaps every
+platform. Disjoint platform recipes can both be added. Invalid recipe JSON uses
+its raw name and platform for the same check; unknown-name files are reported
+with read/parse details without blocking unrelated Apps. A profile cannot contain
+same-name recipes whose platform applicability overlaps. Import never installs Apps or runs
+recipe commands. Review and approve applicable
+recipes with `agent-depot app approve <name> --yes` before using their lifecycle
+commands. Source discovery inclusion remains a transient frontend choice, not a
+persisted change to an existing Source. Skills carry their own Source identity,
+so omitting their Source block does not force registration; the preview names
+unregistered Sources that will be fetched without registering. Existing Source
+rows explain when discovery inclusion differs but is not imported.
+
+The **5 Import/Export** TUI tab offers grouped checklists and the same shared-core
+previews as the CLI. Exclusions and conflicts cannot be selected. Export creates
+a new file only; empty exports write nothing (CLI reports an error). Import adds missing choices without replacing existing ones.
+Imported recipes remain unapproved and Apps are never installed by import.

package/dist/src/app-flow.js

@@ -137,7 +137,8 @@ export function createAppOperations(environment = {}) {
         await chmod(receipts, 0o700);
         await writeFileAtomically(receiptPath(entry), JSON.stringify({ hash: entry.hash }), { mode: 0o600 });
     }
-    async function approvalProblem(entry) {
+    /** Reads recipe identity and approval receipts only; never resolves or runs commands. */
+    async function approvalStatus(entry) {
         if (entry.error || !entry.recipe)
             return { status: "invalid", reason: entry.error };
         if (!entry.applicable)
@@ -154,11 +155,17 @@ export function createAppOperations(environment = {}) {
             if (error.code !== "ENOENT")
                 throw error;
         }
-        if (!approved) {
+        return { status: approved ? "approved" : "needs approval" };
+    }
+    async function approvalProblem(entry) {
+        const approval = await approvalStatus(entry);
+        if (approval.status === "approved")
+            return undefined;
+        if (approval.status === "needs approval") {
             const { executable } = await resolve(entry.recipe.version.argv[0]);
-            return { status: "needs approval", executable };
+            return { status: approval.status, reason: approval.reason, executable };
         }
-        return undefined;
+        return { status: approval.status, reason: approval.reason };
     }
     /** A supplied cache checks recipe approval without running version; omit it for a live check. */
     async function inspect(entry, cached) {
@@ -440,7 +447,7 @@ export function createAppOperations(environment = {}) {
                 throw error;
         });
     }
-    return { checkUpdate, load, preview, approve, inspect, planLifecycle, executeLifecycle, completeManual, cancelManual, trackedApps, previewForget, forgetApp };
+    return { directory, approvalStatus, checkUpdate, load, preview, approve, inspect, planLifecycle, executeLifecycle, completeManual, cancelManual, trackedApps, previewForget, forgetApp };
 }
 /** Concurrent independent checks; one broken App must not hide the rest of a batch. */
 export async function checkAppUpdates(apps) {

package/dist/src/cli.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { checkAppUpdates, createAppOperations } from "./app-flow.js";
 import { describeAppResult, describeManualCompletion, runAppCommand } from "./app-cli.js";
+import { EXPORT_USAGE, IMPORT_USAGE, runProfileExport, runProfileImport } from "./profile-cli.js";
 import { pathsOverlap } from "./path-safety.js";
 import { skillTreeBaseline } from "./skill-discovery.js";
 import { BuiltInSourceError, createSourceOperations, resolveProjectSource, SourceMetadataError, SourceNotFoundError, } from "./sources.js";
@@ -41,6 +42,8 @@ const USAGE = [
     "  agent-depot app approve <name> [--yes]",
     "  agent-depot app install|update|uninstall <name> [--yes] [--manual-done]",
     "  agent-depot app uninstall <name> --forget [--yes]",
+    `  ${EXPORT_USAGE}`,
+    `  ${IMPORT_USAGE}`,
     "  agent-depot tui",
     "  agent-depot --version",
 ].join("\n");
@@ -68,6 +71,8 @@ const SOURCE_SUBCOMMANDS = new Map([
     ["migrate", (values, { operations, dependencies, output }) => runSourceMigration(values, operations, dependencies, output)],
 ]);
 const COMMANDS = new Map([
+    ["import", (values, { operations, dependencies, output }) => runProfileImport(values, operations, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output, dependencies)],
+    ["export", (values, { operations, dependencies, output }) => runProfileExport(values, operations, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output, dependencies.stderr ?? (line => console.error(line)), dependencies.homeDirectory)],
     ["app", (values, { dependencies, output }) => runAppCommand(values, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output)],
     ["install", async (values, { operations, dependencies, output }) => {
             await runInstall(values, operations, dependencies, output);

package/dist/src/profile-cli.js

@@ -0,0 +1,88 @@
+import { readFile } from "node:fs/promises";
+import { buildProfileExport, requireProfileExportSelection, writeProfileExport } from "./profile-export.js";
+import { applyProfileImport, buildProfileImport } from "./profile-import.js";
+import { serializeProfile } from "./profile.js";
+import { CliUsageError } from "./usage-error.js";
+export const EXPORT_USAGE = "agent-depot export [--out <file>] [--no-sources] [--no-skills] [--no-apps] [--source <id|url>...] [--skill <path|name>...] [--app <name>...]";
+export const IMPORT_USAGE = "agent-depot import <file> [--yes] [--no-sources] [--no-skills] [--no-apps] [--source <id|url>...] [--skill <path|name>...] [--app <name>...]";
+export async function runProfileExport(values, operations, apps, output, diagnostic, homeDirectory) {
+    const { filters, out } = parseProfileOptions(values, false);
+    const plan = await buildProfileExport(operations, apps, { ...filters, homeDirectory });
+    for (const line of plan.preview)
+        diagnostic(line);
+    requireProfileExportSelection(plan.profile);
+    const content = serializeProfile(plan.profile);
+    if (out === undefined)
+        output(content.trimEnd());
+    else {
+        await writeProfileExport(out, plan.profile);
+        diagnostic(`Exported profile to ${out}`);
+    }
+    return 0;
+}
+function parseProfileOptions(values, importing) {
+    const sources = [], skills = [], appNames = [];
+    const filters = { sources, skills, apps: appNames };
+    let out;
+    let confirmed = false;
+    for (let index = 0; index < values.length; index++) {
+        const option = values[index];
+        if (option === "--yes" && importing) {
+            if (confirmed)
+                throw new CliUsageError("Duplicate --yes");
+            confirmed = true;
+        }
+        else if (option === "--no-sources")
+            filters.noSources = true;
+        else if (option === "--no-skills")
+            filters.noSkills = true;
+        else if (option === "--no-apps")
+            filters.noApps = true;
+        else if (["--out", "--source", "--skill", "--app"].includes(option)) {
+            const value = values[++index];
+            if (!value || value.startsWith("--"))
+                throw new CliUsageError(`${option} requires a value`);
+            if (option === "--out") {
+                if (importing)
+                    throw new CliUsageError(`Usage: ${IMPORT_USAGE}`);
+                if (out !== undefined)
+                    throw new CliUsageError("Duplicate --out");
+                out = value;
+            }
+            else {
+                const names = option === "--source" ? sources : option === "--skill" ? skills : appNames;
+                if (names.includes(value))
+                    throw new CliUsageError(`Duplicate ${option} ${JSON.stringify(value)}`);
+                names.push(value);
+            }
+        }
+        else
+            throw new CliUsageError(`Usage: ${importing ? IMPORT_USAGE : EXPORT_USAGE}`);
+    }
+    return { filters, out, confirmed };
+}
+export async function runProfileImport(values, operations, apps, output, environment = {}) {
+    const file = values[0];
+    if (!file || file.startsWith("--"))
+        throw new CliUsageError(`Usage: ${IMPORT_USAGE}`);
+    const { filters, confirmed } = parseProfileOptions(values.slice(1), true);
+    const content = await readFile(file, "utf8");
+    let input;
+    try {
+        input = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`${file}: invalid JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const plan = await buildProfileImport(input, operations, apps, filters);
+    for (const line of plan.preview)
+        output(line);
+    if (!confirmed) {
+        output("Import not confirmed; rerun with --yes. Nothing was written.");
+        return 0;
+    }
+    const results = await applyProfileImport(plan, operations, apps, confirmed, output, environment);
+    for (const result of results)
+        output(`${result.status}: ${result.item.label}${result.detail ? `; ${result.detail}` : ""}`);
+    return results.some(result => result.status === "failed") ? 1 : 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);
+}