@iseoane/agent-depot 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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
+
+- **Apps**: user-global applications (for example Engram, CodeGraph, GitNexus) managed through user-declared JSON recipes in the per-user `apps/` directory. Agent Depot delegates the lifecycle to the App's own commands, tracks the installed version and never tracks what an App writes, clones App repositories or ships built-in recipes (ADR 0007).
+- `agent-depot app schema | validate | approve | list`: recipe JSON Schema, validation per platform (WSL counts as Linux), content-hash approval required before any recipe command runs, and listing with installed version and resolved executable.
+- `agent-depot app install | uninstall | update <name>` and `app setup | teardown <name> --host <host>...`: previewed and confirmed steps run without a shell from the home directory; manual steps are shown and confirmed with `--manual-done`; installed state is recorded only when `version` confirms it; `app uninstall --forget` drops tracking explicitly.
+- Latest-version lookup from GitHub Releases, the npm registry or an approved argv; Apps join `update check` and `update apply` (`--app <name>`); an update succeeds only when the version changes, and semver downgrades are never offered.
+- TUI: an "Apps (user-global)" group in Installations (approve, install, uninstall, Host setup/teardown, bulk marks) and App rows in the Updates batch, with lazy version checks so start-up stays fast.
+- Recipe-declared `skills` names/globs exclude App-owned skills from the unmanaged adopt and remove flows.
+- Built-in skill `agent-depot-apprecipe` guides an AI agent to research an App and write valid, platform-aware recipes.
+
+### Changed
+
+- `runProcess` accepts an opt-in `maxStderrBytes`; Source and Skill commands keep their previous behaviour.
+
+### Internal
+
+- Hermetic end-to-end coverage for Apps in the CLI and in a real terminal.
+- Test processes ignore an exported `XDG_STATE_HOME`, so a developer's own state no longer affects the suite.
+- Test processes ignore `FORCE_COLOR`, which `node --test` sets when run from a real terminal; the TUI tests no longer fail under `npm publish` in a TTY.
+
 ## [0.2.1] - 2026-09-30
 
 ### Fixed

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
@@ -468,3 +471,185 @@ entry points and the module-layer boundaries (`cli` -> `application` -> `core`
 - `pnpm test:coverage`: runs the tests with built-in V8 coverage
   (`NODE_V8_COVERAGE`, source maps) into `coverage/v8`, which Fallow reads.
   It rebuilds `dist/` with source maps; no extra dependencies are needed.
+
+## User-global App recipes
+
+Place user-owned JSON recipes in `apps/` next to the per-user `sources.json`
+(Linux/WSL: `${XDG_STATE_HOME:-~/.local/state}/agent-depot/apps`; Windows:
+`%APPDATA%\Agent Depot\apps`). Recipes are never rewritten or supplied by Sources.
+
+```sh
+agent-depot app schema
+agent-depot app validate /path/to/example.json
+agent-depot app list
+agent-depot app approve example --yes
+```
+
+Validation previews every declared argv and its resolved executable but never
+approves recipes (`validate --yes` is rejected). Review the preview before using
+`app approve <name> --yes`: approval authorizes version commands, not just
+read-only behavior. Private, atomically written approval receipts live in sibling
+`app-approvals/` and are keyed to the canonical file path and exact content hash.
+Changed bytes require approval again; restoring approved bytes restores approval.
+`app list` never approves recipes. Invalid recipes are shown with
+reasons; validation exits non-zero for invalid recipes. Other-platform recipes
+are reported as not applicable and never executed. WSL counts as Linux and never
+runs executables whose realpath is under `/mnt/<drive>/`; it skips those PATH
+candidates while looking for Linux executables. Commands spawn the PATH candidate
+rather than the realpath so shims and multicall binaries retain their identity.
+
+Required fields are `name`, `install`, `update`, `uninstall`, and `version`.
+Lifecycle steps contain `argv`, `manual`, or both; manual text is never executed.
+`version` contains safe no-shell `argv` and a JavaScript regex `pattern` with one
+capture group. Commands run from the user's home directory. An unsuccessful or
+unresolvable version check means not installed. The schema describes structure;
+`app validate` additionally enforces argv safety and regex semantics.
+
+### Install, update and uninstall
+
+```sh
+agent-depot app install example          # preview only; exits non-zero until confirmed
+agent-depot app install example --yes
+agent-depot app update example --yes
+agent-depot app uninstall example --yes
+agent-depot app setup example --host pi --host codex --yes
+agent-depot app teardown example --host pi --yes
+```
+
+Each step previews its argv/manual text, resolved executable, home working
+directory and environment. Manual fallback occurs only when a process cannot
+launch, never after a non-zero exit (reported with stdout/stderr). Run the shown
+manual instructions yourself, then attest completion without rerunning argv:
+
+```sh
+agent-depot app install example --manual-done --yes
+agent-depot app uninstall example --manual-done --yes
+```
+
+`--yes` alone does not attest manual completion. Install records a version only
+when the version check succeeds. Uninstall retains tracking while version still
+succeeds; `agent-depot app uninstall example --forget --yes` explicitly removes
+tracking without running any recipe command, even if the recipe is gone.
+Atomic per-App records live in sibling `app-installations/`. Uninstall does not
+implicitly run Host teardown.
+
+`app list` and `update check --scope user-global` resolve latest versions from
+GitHub Releases, npm, or approved `latest.argv`. Missing or failed lookups are
+unknown, never offered as updates. Public HTTP requests send no credentials,
+reject redirects, cap responses at 1 MiB and time out after five seconds.
+
+```sh
+agent-depot update apply --scope user-global --all --yes
+agent-depot update apply --scope user-global --skill 0 --app example --yes
+agent-depot app update example --manual-done --yes
+```
+
+`--all` includes Apps and Skills; repeat `--app <name>` to select Apps alongside
+Skills. App updates run **after Skills** in the same batch. Apps are user-global
+only; `--all --scope project` skips Apps. Every selected step is previewed before the
+batch confirmation; independent failures do not stop the remaining updates.
+Manual batch outcomes are completed separately using `app update --manual-done`.
+Updates record the version confirmed by the recipe's version command, not the
+registry response. Updates require a changed version; unchanged versions fail
+without rewriting installed tracking. Leading `v` and SemVer build-metadata-only
+changes count as unchanged, just as in availability checks. Successful results show
+`installed <old> -> <new> (latest <latest>)`, even when new differs from latest.
+A confirmed manual update preview/fallback saves private version evidence in
+sibling `app-pending-updates/`, so a later `--manual-done` invocation can compare
+against the pre-update version. An attested manual completion consumes this
+evidence even on failure; get a fresh confirmed preview before retrying.
+
+Strict SemVer comparison ignores a leading `v`, orders prereleases and does not
+offer a downgrade when installed is at or ahead of latest. Non-SemVer versions
+use opaque inequality and **may offer a downgrade**. GitHub `/releases/latest`
+excludes drafts and prereleases; npm uses package metadata's `dist-tags.latest`.
+`app list` checks Apps concurrently, preserving listing order. One App check
+failure does not hide other Apps or Skill updates. Lookup failures show reasons
+(redirect, rate limit, HTTP status, timeout, oversized or invalid response).
+
+
+App lifecycle commands are non-interactive: stdin is ignored (EOF), as in the
+existing Skill command runner, and there is no execution timeout. Recipes must
+use non-interactive flags; installers requiring a terminal belong in `manual`
+steps. EOF lets stdin-based prompts fail rather than wait for input, but a
+process ignoring EOF can still hang; cancel it manually. Captured App stdout
+and stderr are each capped at 1 MiB; failures show only their last 4 KiB.
+
+App setup/teardown accepts only Hosts declared for that action. All selected steps
+are previewed before execution; each Host gets an outcome and failures do not stop
+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-cli.js

@@ -0,0 +1,172 @@
+import { PROJECT_HOSTS } from "./project-manifest.js";
+import { APP_RECIPE_SCHEMA } from "./app-schema.js";
+import { checkAppUpdates } from "./app-flow.js";
+import { CliUsageError } from "./usage-error.js";
+export async function runAppCommand(values, apps, output) {
+    const [command, ...args] = values;
+    const usage = "Usage: agent-depot app schema|list; app validate <file>...; app approve <name> [--yes]; app install|update|uninstall <name> [--yes] [--manual-done]; app setup|teardown <name> --host <host>... [--yes] [--manual-done]; app uninstall <name> --forget [--yes] (--manual-done requires a declared manual step)";
+    if (command === "schema" && args.length === 0) {
+        output(JSON.stringify(APP_RECIPE_SCHEMA, null, 2));
+        return 0;
+    }
+    if (command === "list" && args.length === 0) {
+        for (const update of await checkAppUpdates(apps))
+            await show(update.entry, update);
+        return 0;
+    }
+    if (command === "install" || command === "update" || command === "uninstall" || command === "setup" || command === "teardown") {
+        return runLifecycle(command, args, apps, output, usage);
+    }
+    if (command !== "validate" && command !== "approve")
+        throw new CliUsageError(usage);
+    const confirmations = args.filter((arg) => arg === "--yes").length;
+    const selections = command === "approve" ? args.filter((arg) => arg !== "--yes") : args;
+    if (!selections.length || selections.some((arg) => arg.startsWith("--"))
+        || confirmations > 1 || (command === "approve" && selections.length !== 1)) {
+        throw new CliUsageError(usage);
+    }
+    const entries = command === "validate"
+        ? await apps.load(selections)
+        : (await apps.load()).filter((entry) => entry.recipe?.name === selections[0] && entry.applicable);
+    if (!entries.length)
+        throw new Error("No applicable recipe found");
+    let failed = false;
+    for (const entry of entries) {
+        if (entry.error) {
+            await show(entry);
+            failed = true;
+            continue;
+        }
+        if (!entry.applicable) {
+            await show(entry);
+            continue;
+        }
+        output(`Recipe approval preview: ${entry.recipe.name} (${entry.file})`);
+        for (const preview of await apps.preview(entry)) {
+            const argv = preview.argv ? JSON.stringify(preview.argv) : "manual only";
+            output(`${preview.step}: ${argv}\t${preview.executable ?? "unresolved"}\tcwd: ${preview.cwd}`);
+            if (preview.warning)
+                output(preview.warning);
+            if ("manual" in preview && preview.manual) {
+                output(`Manual (never executed): ${preview.manual}`);
+            }
+        }
+        if (command === "approve" && confirmations === 1) {
+            await apps.approve(entry);
+        }
+        else {
+            output(`Approve explicitly with app approve ${JSON.stringify(entry.recipe.name)} --yes after reviewing every argv.`);
+        }
+        await show(entry);
+    }
+    return failed ? 1 : 0;
+    async function show(entry, update) {
+        const result = update?.inspection ?? await apps.inspect(entry);
+        const columns = [
+            entry.recipe?.name ?? entry.file, result.status,
+            result.installedVersion ?? "unknown", result.executable ?? "unresolved",
+        ];
+        if (update) {
+            columns.push(`latest: ${update.latestVersion ?? "unknown"}`, update.status);
+            if (update.reason && update.reason !== result.reason)
+                columns.push(update.reason);
+        }
+        if (result.reason)
+            columns.push(result.reason);
+        output(columns.join("\t"));
+    }
+}
+async function runLifecycle(action, args, apps, output, usage) {
+    const hostAction = action === "setup" || action === "teardown";
+    const hosts = [];
+    const remaining = [];
+    for (let index = 0; index < args.length; index++) {
+        if (args[index] !== "--host") {
+            remaining.push(args[index]);
+            continue;
+        }
+        const host = args[++index];
+        if (!hostAction || !PROJECT_HOSTS.some(value => value === host) || hosts.includes(host)) {
+            throw new CliUsageError(usage);
+        }
+        hosts.push(host);
+    }
+    if (hostAction && !hosts.length)
+        throw new CliUsageError(usage);
+    const flags = remaining.filter(arg => arg.startsWith("--"));
+    const names = remaining.filter(arg => !arg.startsWith("--"));
+    const confirmed = flags.includes("--yes");
+    const done = flags.includes("--manual-done");
+    const forget = flags.includes("--forget");
+    const invalidSelection = names.length !== 1;
+    const duplicateFlags = new Set(flags).size !== flags.length;
+    const unknownFlag = flags.some(flag => !["--yes", "--manual-done", "--forget"].includes(flag));
+    const incompatibleForget = forget && (action !== "uninstall" || done);
+    if (invalidSelection || duplicateFlags || unknownFlag || incompatibleForget) {
+        throw new CliUsageError(usage);
+    }
+    const name = names[0];
+    if (forget) {
+        const record = await apps.previewForget(name);
+        output(`Forget App tracking only: ${name} (${record.file}); no recipe commands will run`);
+        await apps.forgetApp(name, confirmed);
+        output(`${name}: untracked`);
+        return 0;
+    }
+    const entries = (await apps.load()).filter(entry => entry.applicable && entry.recipe?.name === name);
+    if (entries.length !== 1)
+        throw new Error("No unique applicable recipe found");
+    // Validate and preview the whole selection before executing any Host.
+    const plans = await Promise.all((hostAction ? hosts : [undefined]).map(host => apps.planLifecycle(entries[0], action, host)));
+    for (const plan of plans)
+        showPlan(plan);
+    if (!confirmed)
+        throw new Error("App step not confirmed; rerun with --yes after reviewing the preview");
+    let failed = false;
+    for (const plan of plans) {
+        try {
+            if (await applyPlan(plan) !== 0)
+                failed = true;
+        }
+        catch (error) {
+            if (!hostAction)
+                throw error;
+            output(`${name} (${plan.host}): failed`);
+            output(error instanceof Error ? error.message : String(error));
+            failed = true;
+        }
+    }
+    return failed ? 1 : 0;
+    function showPlan(plan) {
+        output(`App ${name} ${action}${plan.host ? ` (${plan.host})` : ""}: ${plan.argv ? JSON.stringify(plan.argv) : "manual only"}\t${plan.executable ?? "unresolved"}\tcwd: ${plan.cwd}\tenvironment: ${plan.environment}`);
+        if (plan.warning)
+            output(plan.warning);
+        if (plan.manual)
+            output(`Manual (never executed): ${plan.manual}`);
+    }
+    async function applyPlan(plan) {
+        const result = done ? await apps.completeManual(plan, true) : await apps.executeLifecycle(plan, true);
+        output(`${name}${plan.host ? ` (${plan.host})` : ""}: ${describeAppResult(result)}`);
+        if (result.reason)
+            output(result.reason);
+        if (result.status === "manual required") {
+            output(`Manual (never executed): ${result.manual}`);
+            output(describeManualCompletion(plan));
+        }
+        return result.status === "installed" || result.status === "untracked" || result.status === "completed" ? 0 : 1;
+    }
+}
+/** Copyable completion command for the platform's documented shell. */
+export function describeManualCompletion(plan) {
+    const name = plan.entry.recipe.name;
+    const quotedName = process.platform === "win32"
+        ? "'" + name.replaceAll("'", "''") + "'"
+        : "'" + name.replaceAll("'", "'\\''") + "'";
+    const shell = process.platform === "win32" ? "PowerShell" : "POSIX shell";
+    return `After completing it, run app ${plan.action} ${quotedName}${plan.host ? ` --host ${plan.host}` : ""} --manual-done --yes to check version (${shell}).`;
+}
+export function describeAppResult(result) {
+    return result.status === "installed" && result.previousVersion
+        ? `installed ${result.previousVersion} -> ${result.installedVersion} (latest ${result.latestVersion ?? "unknown"})`
+        : result.status;
+}