@iseoane/agent-depot 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,53 @@ 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.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
+
+- A project manifest that pins a built-in Skill to another Agent Depot version stays loadable; `install --manifest` skips that Skill with its reason and installs the rest.
+- `install --manifest` now fails with exit code 1 ("Nothing to install") when every Skill is skipped, and prints a summary line when only some are.
+- `--help`, `-h` and `help` print the usage and exit 0.
+- The Updates view names the reason on the collapsed "cannot be checked" row.
+- Unmanaged symlink identity includes birth time and size, so a replaced symlink is no longer mistaken for the original.
+- Bulk actions in the TUI detect drift strictly: a change to the installation records outside the batch stops the affected item and leaves it untouched.
+- The TUI only treats real terminal escape sequences as escape remnants, so pasting text such as `Ok` into an input keeps it.
+- Updates scope keys (`t`, `p`, `g`) are looked up in a Map, so prototype property names can never match.
+
+### Changed
+
+- The npm tarball is smaller: source maps and Skill tests are excluded.
+- README links are absolute GitHub URLs so they work on npm.
+
+### Internal
+
+- Every source file is covered by a dependency-boundary zone (fallow audit); the version test path was fixed.
+- Duplicated blocks removed (18 clone groups down to 3) in project installation and the TUI views.
+- Cognitive complexity reduced in the catalog, updates and installations views and their key handlers; `installations-view.tsx` and `catalog-view.tsx` split into focused modules.
+- Characterization tests for the complex functions in `src/path-safety.ts`.
+
 ## [0.2.0] - 2026-09-30
 
 ### BREAKING

package/README.md

@@ -47,7 +47,9 @@ Agent Depot is reported as not updatable (update Agent Depot first).
 
 ## Usage
 
-With the package installed (or via `npx @iseoane/agent-depot`):
+With the package installed (or via `npx @iseoane/agent-depot`). `agent-depot --help`
+(also `-h` or `help`) prints the usage and exits 0; running it without arguments
+or with an unknown command is a usage error and exits 1.
 
 ```sh
 agent-depot source list
@@ -249,7 +251,10 @@ Sources require a fixed 40- or 64-character Git commit. For the built-in
 Source, `latest` tracks the installed Agent Depot package, while a fixed policy
 is accepted only when its value exactly equals that package's current version;
 other values fail closed because the requested package version cannot be
-reproduced. The built-in Source does not support `--ref`, and the CLI rejects it
+reproduced. A manifest written by another Agent Depot stays loadable: a built-in
+Skill pinned to a different version shows as unknown in `update check` ("pinned
+to Agent Depot X; running Y") and is skipped by `install --manifest`, while the
+other Skills keep working. The built-in Source does not support `--ref`, and the CLI rejects it
 explicitly. External `latest` may track an explicit mutable safe ref, but an
 immutable commit ref must use a fixed policy matching that commit. The
 `--portable-v1` flag requires the validated portable format rule; compatibility
@@ -410,7 +415,7 @@ Safety model:
 - Batch installs and removals apply item by item; one failure does not stop the
   others and each item reports its own result.
 
-See [CONTEXT.md](CONTEXT.md) for the domain terms and [docs/adr](docs/adr) for the
+See [CONTEXT.md](https://github.com/iseoane/agent-depot/blob/main/CONTEXT.md) for the domain terms and [docs/adr](https://github.com/iseoane/agent-depot/tree/main/docs/adr) for the
 decisions behind the TUI.
 
 ## Configuration and cache
@@ -463,3 +468,112 @@ 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.

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;
+}