@iseoane/agent-depot 0.2.1 → 0.3.0

package/dist/src/tui/updates.js

@@ -1,8 +1,14 @@
+import { checkAppUpdates, createAppOperations } from "../app-flow.js";
 import { formatVersionPolicy } from "../skill-install.js";
 import { applyConfirmedUpdates, describeUpdatePreview, loadUpdates, previewUpdateCandidates, readScopeInstallations, } from "../update-flow.js";
 import { formatVersionEvidence } from "./installations.js";
 /** Every scope the view can assess, in display order. */
 export const UPDATE_SCOPES = ["project", "user-global"];
+const APP_STATUS_LABEL = {
+    "update available": "update available",
+    current: "up to date",
+    unknown: "cannot assess",
+};
 const STATUS_LABEL = {
     updateable: "update available",
     current: "up to date",
@@ -61,6 +67,7 @@ async function refreshSources(operations, selections) {
  * Changes nothing but the Source caches.
  */
 export async function loadUpdateRows(operations, environment, options) {
+    const apps = createAppOperations({ homeDirectory: environment.homeDirectory, ...environment.appEnvironment });
     let refresh = { attempted: false, refreshed: [], failed: [], unreadable: [] };
     if (options.refresh) {
         options.onPhase?.("refreshing");
@@ -81,6 +88,7 @@ export async function loadUpdateRows(operations, environment, options) {
         }
     }));
     const rows = results.flatMap(({ scope, loaded }) => (loaded?.assessment.items ?? []).map((item) => ({
+        kind: "skill",
         key: `${scope}:${item.id}`,
         scope,
         item,
@@ -91,7 +99,29 @@ export async function loadUpdateRows(operations, environment, options) {
         status: STATUS_LABEL[item.status],
         reason: item.reason,
     })));
-    return { results, rows, refresh, checkedAt: (options.now ?? Date.now)() };
+    let appChecks = [];
+    let appError;
+    try {
+        appChecks = await checkAppUpdates(apps);
+    }
+    catch (error) {
+        appError = errorText(error);
+    }
+    for (const check of appChecks) {
+        rows.push({
+            kind: "app",
+            key: `app:${check.entry.file}`,
+            scope: "user-global",
+            check,
+            path: `App: ${check.entry.recipe?.name ?? check.entry.file}`,
+            policy: "latest",
+            installed: check.installedVersion ?? "?",
+            available: check.latestVersion ?? "?",
+            status: APP_STATUS_LABEL[check.status],
+            reason: check.reason ?? check.inspection.reason ?? check.inspection.status,
+        });
+    }
+    return { results, rows, refresh, apps, appError, checkedAt: (options.now ?? Date.now)() };
 }
 /** `just now`, `42s ago`, `5 min ago`, `2 h ago`. */
 export function formatAgo(elapsedMs) {
@@ -108,10 +138,12 @@ export function formatAgo(elapsedMs) {
 /** Plan step: previews the selection from the assessed snapshots, scope by scope. Changes nothing. */
 export async function prepareUpdates(data, selected) {
     const groups = [];
+    const appPlans = [];
+    const appFailures = [];
     const lines = [];
     const failures = [];
     for (const { scope, loaded } of data.results) {
-        const items = selected.filter((row) => row.scope === scope).map((row) => row.item);
+        const items = selected.filter((row) => row.kind !== "app" && row.scope === scope).map((row) => row.item);
         if (!loaded || items.length === 0)
             continue;
         const { context } = loaded;
@@ -126,10 +158,22 @@ export async function prepareUpdates(data, selected) {
             overwriteShown: new Set(outcome.plans.filter((plan) => plan.overwriteRequired).map((plan) => plan.item.id)),
         });
     }
+    for (const row of selected) {
+        if (row.kind !== "app" || !data.apps)
+            continue;
+        try {
+            const plan = await data.apps.planLifecycle(row.check.entry, "update", undefined, row.check);
+            appPlans.push(plan);
+            lines.push(`Environment: ${plan.environment}`, row.path, `Version: ${plan.previousVersion} -> ${plan.latestVersion ?? "unknown"}`, ...(plan.argv ? [`argv: ${JSON.stringify(plan.argv)}`, `Executable: ${plan.executable ?? "unavailable"}`] : []), ...(plan.manual ? [`Manual: ${plan.manual}`] : []), `Working directory: ${plan.cwd}`, ...(plan.warning ? [plan.warning] : []));
+        }
+        catch (error) {
+            appFailures.push(`Failed ${row.path}: preview failed: ${errorText(error)}`);
+        }
+    }
     return {
-        groups,
+        groups, apps: data.apps, appPlans, appFailures,
         lines,
-        applicable: groups.flatMap((group) => group.applicable),
+        applicable: [...groups.flatMap((group) => group.applicable), ...appPlans],
         failures,
         nonCanonicalPaths: groups.flatMap((group) => group.nonCanonicalPaths.map((location) => ({ scope: group.scope, path: location }))),
     };
@@ -138,9 +182,11 @@ export async function prepareUpdates(data, selected) {
  * Applies exactly the previewed items, scope by scope. Confirming the preview
  * confirms overwriting and external commands; a non-canonical path is applied
  * only when the caller passes it (with its scope) after the separate confirmation.
+ * confirmManual pauses for manual completion, showing the fallback reason. A false
+ * answer (or absent callback) cancels and clears pending update evidence.
  * A Skill that became locally modified after the preview fails instead of being overwritten.
  */
-export async function runUpdates(prepared, confirmedPaths) {
+export async function runUpdates(prepared, confirmedPaths, confirmManual) {
     const updated = [];
     const failedLines = [];
     for (const group of prepared.groups) {
@@ -150,6 +196,31 @@ export async function runUpdates(prepared, confirmedPaths) {
         updated.push(...result.updated.map((item) => `Updated ${item.selection.path}`));
         failedLines.push(...result.failed.map((item) => `Failed ${item.selection.path}: ${item.error ?? "unknown error"}`));
     }
+    for (const plan of prepared.appPlans) {
+        const name = `App: ${plan.entry.recipe.name}`;
+        try {
+            const apps = prepared.apps;
+            if (!apps)
+                throw new Error("App operations unavailable; check again");
+            let result = await apps.executeLifecycle(plan, true);
+            if (result.status === "manual required") {
+                if (!await confirmManual?.(plan, result.reason)) {
+                    await apps.cancelManual(plan);
+                    failedLines.push(`Cancelled ${name}${result.reason ? `: ${result.reason}` : ""}`);
+                    continue;
+                }
+                result = await apps.completeManual(plan, true);
+            }
+            if (result.status === "failed")
+                failedLines.push(`Failed ${name}: ${result.reason}`);
+            else
+                updated.push(`Updated ${name}: installed ${result.previousVersion} -> ${result.installedVersion} (latest ${result.latestVersion ?? "unknown"})`);
+        }
+        catch (error) {
+            failedLines.push(`Failed ${name}: ${errorText(error)}`);
+        }
+    }
+    failedLines.push(...prepared.appFailures);
     const previewFailed = prepared.failures.map(({ item, message }) => `Failed ${item.selection.path}: preview failed: ${message}`);
     const failed = failedLines.length + previewFailed.length;
     return {

package/dist/src/unmanaged-removal.js

@@ -21,11 +21,13 @@ export async function removeInspectedUnmanagedSkill(context, inspection, expecte
     const latestManagedInstallations = await operations.listUserGlobalInstallations();
     assertManagedInstallationRecordsUnchanged(expectedManagedInstallations, latestManagedInstallations);
     const latestInspection = await inspectUserGlobalSkillRemoval(inspection.path, {
+        ...context,
         homeDirectory,
         managedInstallations: latestManagedInstallations,
     });
     assertUnmanagedInspectionUnchanged(inspection, latestInspection);
     await removeUserGlobalSkill(inspection, {
+        ...context,
         homeDirectory,
         managedInstallations: latestManagedInstallations,
         readManagedInstallations: async () => operations.listUserGlobalInstallations(),
@@ -38,6 +40,7 @@ export async function removeInspectedUnmanagedSymlink(context, inspection, expec
     const latestManagedInstallations = await operations.listUserGlobalInstallations();
     assertManagedInstallationRecordsUnchanged(expectedManagedInstallations, latestManagedInstallations);
     await removeUserGlobalSymlink(inspection, {
+        ...context,
         homeDirectory,
         managedInstallations: latestManagedInstallations,
         readManagedInstallations: async () => operations.listUserGlobalInstallations(),

package/dist/src/user-global-skill-inventory.js

@@ -2,6 +2,7 @@ import { lstat, readdir, readFile, readlink, rename, rm, unlink } from "node:fs/
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import path from "node:path";
+import { assertSkillNotAppOwned, loadAppOwnedSkillFilter } from "./app-owned-skills.js";
 import { pathsOverlap } from "./path-safety.js";
 import { readExistingSkillTree } from "./skill-adoption.js";
 import { parseSkillFrontmatter, skillTreeBaseline } from "./skill-discovery.js";
@@ -49,7 +50,8 @@ export async function scanUserGlobalSkillInventory(options = {}) {
     const skipped = [];
     const exposures = [];
     const symlinks = [];
-    const state = { managedPaths, managedCanonicalPaths, entries, skipped, exposures, symlinks };
+    const isAppOwned = await loadAppOwnedSkillFilter({ ...options, homeDirectory });
+    const state = { isAppOwned, managedPaths, managedCanonicalPaths, entries, skipped, exposures, symlinks };
     for (const root of GLOBAL_SKILL_ROOTS) {
         const rootPath = path.join(homeDirectory, ...root.relativePath);
         await scanRoot(root, rootPath, homeDirectory, state);
@@ -106,6 +108,8 @@ async function listScannableRoot(root, rootPath, homeDirectory, skipped) {
 }
 async function scanRootEntry(root, name, candidatePath, homeDirectory, state) {
     const { managedPaths, entries, skipped } = state;
+    if (!managedPaths.has(pathKey(candidatePath)) && state.isAppOwned(name))
+        return;
     if (isTransientName(name)) {
         skipped.push({ name, path: candidatePath, root: root.kind, reason: "excluded-transient" });
         return;
@@ -288,6 +292,7 @@ async function inspectCanonicalTarget(candidatePath) {
 export async function inspectUserGlobalSkillRemoval(candidatePath, options) {
     const homeDirectory = path.resolve(options.homeDirectory);
     const targetPath = validateExplicitGlobalPath(candidatePath, homeDirectory);
+    await assertSkillNotAppOwned(path.basename(candidatePath), options);
     const fileSystem = options.fileSystem ?? nodeFileSystem;
     await assertRealGlobalAncestors(homeDirectory, path.dirname(targetPath), fileSystem);
     const managedPaths = managedProtectionPaths(homeDirectory, options.managedInstallations);
@@ -382,6 +387,7 @@ export async function removeUserGlobalSkill(inspection, options) {
 export async function inspectUserGlobalSymlinkRemoval(candidatePath, options) {
     const homeDirectory = path.resolve(options.homeDirectory);
     const linkPath = validateExplicitGlobalPath(candidatePath, homeDirectory);
+    await assertSkillNotAppOwned(path.basename(candidatePath), options);
     const fileSystem = options.fileSystem ?? nodeFileSystem;
     await assertRealGlobalAncestors(homeDirectory, path.dirname(linkPath), fileSystem);
     const managedPath = managedProtectionPaths(homeDirectory, options.managedInstallations)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iseoane/agent-depot",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A cross-platform catalog for reusable coding-agent skills.",
   "license": "MIT",
   "author": "iseoane",
@@ -44,9 +44,9 @@
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
     "typecheck": "tsc --noEmit",
     "lint": "eslint \"src/**/*.{ts,tsx}\" \"tests/**/*.{ts,tsx}\"",
-    "test": "pnpm build && node --test \"dist/tests/*.test.js\"",
-    "test:single": "pnpm build && node -e \"const { spawnSync } = require('node:child_process'); const input = process.argv[1] || 'tests/version.test.ts'; const file = input.replace(/^tests[\\\\/]/, 'dist/tests/').replace(/\\\\.ts$/i, '.js'); process.exit(spawnSync(process.execPath, ['--test', file], { stdio: 'inherit' }).status ?? 1);\"",
-    "test:coverage": "node -e \"require('node:fs').rmSync('coverage',{recursive:true,force:true})\" && tsc -p tsconfig.coverage.json && node -e \"const { spawnSync } = require('node:child_process'); process.exit(spawnSync(process.execPath, ['--enable-source-maps','--test','--test-reporter=dot','dist/tests/*.test.js'], { stdio: 'inherit', env: { ...process.env, NODE_V8_COVERAGE: 'coverage/v8' } }).status ?? 1);\"",
+    "test": "pnpm build && node --test --import ./dist/tests/isolated-env.js \"dist/tests/*.test.js\"",
+    "test:single": "pnpm build && node -e \"const { spawnSync } = require('node:child_process'); const input = process.argv[1] || 'tests/version.test.ts'; const file = input.replace(/^tests[\\\\/]/, 'dist/tests/').replace(/\\\\.ts$/i, '.js'); process.exit(spawnSync(process.execPath, ['--import', './dist/tests/isolated-env.js', '--test', file], { stdio: 'inherit' }).status ?? 1);\"",
+    "test:coverage": "node -e \"require('node:fs').rmSync('coverage',{recursive:true,force:true})\" && tsc -p tsconfig.coverage.json && node -e \"const { spawnSync } = require('node:child_process'); process.exit(spawnSync(process.execPath, ['--enable-source-maps','--import','./dist/tests/isolated-env.js','--test','--test-reporter=dot','dist/tests/*.test.js'], { stdio: 'inherit', env: { ...process.env, NODE_V8_COVERAGE: 'coverage/v8' } }).status ?? 1);\"",
     "audit:dead-code": "npx --yes fallow@3.30.0 dead-code --fail-on-issues",
     "audit:dupes": "npx --yes fallow@3.30.0 dupes",
     "audit:health": "pnpm test:coverage && npx --yes fallow@3.30.0 health --coverage coverage/v8 --min-score 85",

package/skills/agent-depot-apprecipe/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: "agent-depot-apprecipe"
+description: "Trigger: App recipe creation or repair. Research an App's actual install channel and write platform-aware Agent Depot recipes."
+license: MIT
+metadata:
+  author: "iseoane"
+  version: "1.0"
+---
+
+## Activation Contract
+
+Use for creating or repairing user-global App recipes, not portable Skills.
+
+## Hard Rules
+
+- Read `agent-depot app schema` first: it is the format source of truth. Research upstream README, install docs and releases through the web or GitHub API; never clone the App repository.
+- Write user-owned JSON in the environment-local `apps/` beside `sources.json`. Preserve existing files unless the user authorizes replacement. Keep Apps out of Sources and project manifests.
+- Never approve a recipe on the user's behalf. Approval belongs to the user via `agent-depot app approve <name> --yes`; changed bytes need renewed approval. Validation is not approval.
+- Use bare executable-plus-arguments arrays, without shells, shell syntax, credentials or environment assignments. Script-only routes (`curl | sh`, PowerShell scripts, `.cmd`) belong in `manual` text, never pipe-to-shell argv. Agent Depot displays manual text without executing it.
+- Steps run from the user's home with stdin EOF and no timeout. Use non-interactive flags; terminal-dependent installers belong in manual steps.
+
+## Decision Gates
+
+| Evidence | Recipe decision |
+|---|---|
+| Identical steps on all supported platforms | Omit `platform`. |
+| Steps differ by OS or architecture | Use separate files with the same App `name` and explicit `linux`, `windows` or `darwin`; ask about architecture where needed. Never create duplicate applicable names. |
+| Unsupported platform | Report it; invent no steps. WSL is Linux, not Windows. |
+| Several installs or uncertain channel | List every path/channel and ask the user to choose before writing lifecycle steps. |
+| brew / npm / pipx | Derive update and uninstall from that channel: upgrade/uninstall, global install/uninstall, or upgrade/uninstall respectively. |
+| Go install / release binary | Use the documented update route and a manual binary-removal step. |
+| App has its own uninstall | Prefer it after verifying scope and non-interactive flags; explain remaining channel cleanup. |
+
+## Execution Steps
+
+1. Record upstream evidence and platform support. Inspect all PATH matches (`which -a`/`whence -a`, or Windows `Get-Command -All`), resolved paths, and channel inventories such as `brew list`, `npm ls -g` or `pipx list`. List Windows shims seen from WSL separately: `/mnt/<drive>/` executables cannot serve a Linux recipe. Finish only when the actual channel is established or the user has chosen one.
+2. Write required `name`, `install`, `update`, `uninstall`, and `version`. Each lifecycle step uses `argv`, `manual`, or both; manual fallback applies only to spawn failure, never non-zero exit. `version` needs read-only argv and a JavaScript regex with exactly one capture group. Choose optional `latest` as `github: owner/repo`, `npm: package`, or read-only `argv` plus `pattern`; omit it when unknown. Consult [the illustrative example](assets/example.md), not as upstream command evidence.
+3. Put user-global Host wiring in optional `setup`/`teardown` maps keyed by `pi`, `claude`, `codex`, or `opencode`. Keep install separate; uninstall never implicitly runs teardown. Delegate wiring to App commands or manual user instructions, not direct agent edits of Host configuration. Exclude project initialization.
+4. Declare optional `skills` only for documented App-owned directory/link names. Match whole names case-sensitively; only `*` is special, while `?` and brackets are literal. Reject empty/whitespace-only, path separators, NUL and star-only patterns. These declarations filter unmanaged adoption/removal even before approval/install; they verify no artifacts or provenance.
+5. Run `agent-depot app validate <file>...` for current-platform recipes. Fix structural errors; report unapproved recipes as needs approval, not runtime-verified. Version commands run only for approved applicable content. Mark other platforms unverified. After user approval, the user can inspect `app list` and separately preview `app install|update|uninstall <name>` or `app setup|teardown <name> --host <host>`.
+
+## Output Contract
+
+Return file paths, platform/channel evidence, validation results and runtime-verification limits; unsupported platforms; omitted optional fields and why; license, telemetry/update-check behavior (or unknown); and conflicting duplicate install routes, including plugin-marketplace versus setup routes. Explain that version alone determines installed state, updates require a changed version, and unknown latest is not an available update. End with the user's approval command, without running it.

package/skills/agent-depot-apprecipe/assets/example.md

@@ -0,0 +1,25 @@
+# Illustrative recipe shape
+
+This fictional App is a format example, not a recommended installation or shipped
+App recipe. Replace commands with verified upstream evidence and the chosen
+channel. Omitted platform means identical steps everywhere; optional fields may
+be omitted rather than populated speculatively.
+
+```json
+{
+  "name": "example-tool",
+  "install": { "argv": ["npm", "install", "-g", "example-tool"] },
+  "update": { "argv": ["npm", "install", "-g", "example-tool"] },
+  "uninstall": { "argv": ["npm", "uninstall", "-g", "example-tool"] },
+  "version": { "argv": ["example-tool", "--version"], "pattern": "(\\d+\\.\\d+\\.\\d+)" },
+  "latest": { "npm": "example-tool" },
+  "setup": { "claude": { "argv": ["example-tool", "setup", "claude", "--yes"] } },
+  "teardown": { "claude": { "manual": "Follow the documented example-tool Claude teardown instructions." } },
+  "skills": ["example-tool-*"]
+}
+```
+
+Use `latest: { "github": "owner/repo" }` for public GitHub Releases, or
+`latest: { "argv": ["example-tool", "latest"], "pattern": "(\\d+\\.\\d+\\.\\d+)" }`
+for a documented read-only command. Choose one latest signal, not a combination.
+A step with both `argv` and `manual` falls back only when spawning fails.