@iseoane/agent-depot 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.1] - 2026-10-01
+
+### Changed
+
+- CI uses `actions/checkout@v7`, `actions/setup-node@v7` and `pnpm/action-setup@v6`, which run on Node.js 24 instead of the deprecated Node.js 20.
+- The App and Profile modules are assigned to dependency-boundary zones, so `pnpm audit:dead-code` passes again.
+- README: the Usage block lists the `app`, `export` and `import` commands, and Static analysis documents the `tui` and `tooling` zones.
+
+## [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

@@ -75,6 +75,11 @@ agent-depot uninstall --cli
 agent-depot uninstall --skills --yes
 agent-depot uninstall --unmanaged-skill <exact-global-path> --yes
 agent-depot uninstall --data --yes
+agent-depot app list
+agent-depot app approve <name> --yes
+agent-depot app install <name> --yes
+agent-depot export --out profile.json
+agent-depot import profile.json --yes
 agent-depot tui
 agent-depot --version
 ```
@@ -380,7 +385,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 +394,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 +405,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
@@ -456,8 +464,11 @@ node dist/src/cli.js --version
 
 [Fallow](https://docs.fallow.tools) 3.30.0 runs through `npx --yes fallow@3.30.0`
 (pinned, no dependency installed) and reads `.fallowrc.json`, which defines the
-entry points and the module-layer boundaries (`cli` -> `application` -> `core`
--> `infrastructure`; imports may only point downward).
+entry points and the module-layer boundaries (`cli` -> `tui` -> `application`
+-> `core` -> `infrastructure`; imports may only point downward, and `cli` may
+also use the lower layers directly). `scripts/**` forms an isolated `tooling`
+zone. Every source file must belong to a zone; App and Profile modules sit in
+`application`, except `atomic-file.ts` in `infrastructure`.
 
 - `pnpm audit:dead-code`: unused files, exports and dependencies, plus
   boundary violations. Must be clean.
@@ -577,3 +588,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;
+    }
+}