@iseoane/agent-depot 0.6.4 → 0.6.5

package/dist/src/cli.js

@@ -6,12 +6,14 @@ import path from "node:path";
 import { checkAppUpdates, createAppOperations } from "./app-flow.js";
 import { describeAppResult, describeManualCompletion, runAppCommand } from "./app-cli.js";
 import { createPackageOperations } from "./package-flow.js";
-import { describeLifecyclePlan, describePackageResult, describePackageUpdateCheck, formatPackageSelection, packageSelectionMatches, runPackageCommand } from "./package-cli.js";
+import { describeLifecyclePlan, describePackageResult, describePackageUpdateCheck, formatPackageSelection, packageSelectionMatches, planWithRefresh, runPackageCommand } from "./package-cli.js";
 import { selectionKey } from "./package-model.js";
 import { EXPORT_USAGE, IMPORT_USAGE, runProfileExport, runProfileImport } from "./profile-cli.js";
 import { pathsOverlap } from "./path-safety.js";
+import { withChildOutput } from "./process-runner.js";
+import { createProgress, NO_PROGRESS } from "./progress.js";
 import { skillTreeBaseline } from "./skill-discovery.js";
-import { BuiltInSourceError, createSourceOperations, resolveProjectSource, SourceMetadataError, SourceNotFoundError, } from "./sources.js";
+import { BUILT_IN_SOURCE, BuiltInSourceError, createSourceOperations, resolveProjectSource, SourceMetadataError, SourceNotFoundError, } from "./sources.js";
 import { AGENT_DEPOT_PACKAGE_NAME, AGENT_DEPOT_PACKAGE_VERSION, builtinPinMismatch, defaultProjectManifestPath, parseProjectManifest, ProjectManifestStore, PROJECT_HOSTS, } from "./project-manifest.js";
 import { inspectProjectSkillInstallation, assertNoOverlappingProjectSkillRemovalTargets, } from "./project-installation.js";
 import { selectUpdateBatch, UpdateBatchSelectionError, } from "./update-batch.js";
@@ -57,6 +59,10 @@ const USAGE = [
     `  ${IMPORT_USAGE}`,
     "  agent-depot tui",
     "  agent-depot --version",
+    "",
+    "Options for every command, anywhere on the line:",
+    "  --verbose  stream the full child output (npm, pi, git, App commands) to stderr line by line as it runs,",
+    "             instead of a spinner and the last few lines; stdout is unchanged.",
 ].join("\n");
 const INSTALL_USAGE = "Usage: agent-depot install --scope <project|user-global> --source <id> --skill <path> --host <host>... --version <latest|version> [--ref <git-ref>] [--method <json>] --portable-v1 [--overwrite --yes] [--confirm-additional-host]";
 const DISCOVER_USAGE = "Usage: agent-depot discover <source-id> [source-id...]\nSelect at least one Source ID explicitly; run `agent-depot source list` to see registered Sources";
@@ -74,11 +80,12 @@ const SOURCE_SUBCOMMANDS = new Map([
         }],
     ["add", async (values, { operations, output }) => {
             requireArgumentCount(values, 1, "source add <url>");
+            // Registration only: nothing is cloned until the first refresh, so there is no long step to report.
             const source = await operations.addGitSource(values[0]);
             output(`Added Git Source: ${source.id}\t${source.url}`);
         }],
     ["refresh", runSourceRefresh],
-    ["remove", (values, { operations, dependencies, output }) => runSourceRemoval(values, operations, dependencies, output)],
+    ["remove", (values, { operations, dependencies, output, progress }) => runSourceRemoval(values, operations, dependencies, output, progress)],
     ["migrate", (values, { operations, dependencies, output }) => runSourceMigration(values, operations, dependencies, output)],
 ]);
 function packageOperationsFor(dependencies, operations) {
@@ -89,34 +96,34 @@ function packageOperationsFor(dependencies, operations) {
     });
 }
 const COMMANDS = new Map([
-    ["import", (values, { operations, dependencies, output }) => runProfileImport(values, operations, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output, { ...dependencies, packageOperations: packageOperationsFor(dependencies, operations) })],
-    ["export", (values, { operations, dependencies, output }) => runProfileExport(values, operations, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output, dependencies.stderr ?? (line => console.error(line)), dependencies.homeDirectory, packageOperationsFor(dependencies, operations))],
-    ["app", (values, { dependencies, output }) => runAppCommand(values, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output)],
-    ["package", (values, { operations, dependencies, output }) => runPackageCommand(values, packageOperationsFor(dependencies, operations), operations, output)],
-    ["install", async (values, { operations, dependencies, output }) => {
-            await runInstall(values, operations, dependencies, output);
+    ["import", (values, { operations, dependencies, output, progress }) => runProfileImport(values, operations, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output, { ...dependencies, packageOperations: packageOperationsFor(dependencies, operations) }, progress)],
+    ["export", (values, { operations, dependencies, output, errorOutput, progress }) => runProfileExport(values, operations, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output, errorOutput, dependencies.homeDirectory, packageOperationsFor(dependencies, operations), progress)],
+    ["app", (values, { dependencies, output, progress }) => runAppCommand(values, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output, progress)],
+    ["package", (values, { operations, dependencies, output, progress }) => runPackageCommand(values, packageOperationsFor(dependencies, operations), operations, output, progress)],
+    ["install", async (values, { operations, dependencies, output, progress }) => {
+            await runInstall(values, operations, dependencies, output, progress);
             return 0;
         }],
-    ["update", (values, { operations, dependencies, output }) => runUpdate(values, operations, dependencies, output)],
-    ["self", async (values, { dependencies, output }) => {
+    ["update", (values, { operations, dependencies, output, progress }) => runUpdate(values, operations, dependencies, output, progress)],
+    ["self", async (values, { dependencies, output, progress }) => {
             if (values[0] !== "update")
                 throw new CliUsageError("Usage: agent-depot self update [--yes]");
-            return runSelfUpdate(values.slice(1), dependencies, output);
+            return runSelfUpdate(values.slice(1), dependencies, output, progress);
         }],
-    ["skill", async (values, { operations, dependencies, output }) => {
+    ["skill", async (values, { operations, dependencies, output, progress }) => {
             if (values[0] === "remove") {
-                await runSkillRemoval(values.slice(1), operations, dependencies, output);
+                await runSkillRemoval(values.slice(1), operations, dependencies, output, progress);
             }
             else if (values[0] === "host" && values[1] === "add") {
-                await runSkillHostAdd(values.slice(2), operations, dependencies, output);
+                await runSkillHostAdd(values.slice(2), operations, dependencies, output, progress);
             }
             else {
                 throw new CliUsageError(USAGE);
             }
             return 0;
         }],
-    ["uninstall", async (values, { operations, dependencies, output }) => {
-            await runUninstall(values, operations, dependencies, output);
+    ["uninstall", async (values, { operations, dependencies, output, progress }) => {
+            await runUninstall(values, operations, dependencies, output, progress);
             return 0;
         }],
     ["discover", async (values, { operations, output }) => {
@@ -162,7 +169,7 @@ const COMMANDS = new Map([
             return 0;
         }],
 ]);
-async function runSourceRefresh(values, { operations, output }) {
+async function runSourceRefresh(values, { operations, output, progress }) {
     if (values.length < 1 || values.length > 2 || (values.length === 2 && values[1] !== "--yes")) {
         throw new CliUsageError("Usage: agent-depot source refresh <id> [--yes]");
     }
@@ -174,13 +181,21 @@ async function runSourceRefresh(values, { operations, output }) {
     if (values[1] !== "--yes") {
         throw new CliUsageError("Refresh not confirmed; rerun with --yes to continue");
     }
-    const refreshed = await operations.refreshSource(source.id);
+    // `git clone`/`fetch` may ask for credentials on the terminal, so this step never animates.
+    const refreshed = await progress.run(`Refreshing Git Source ${source.id}`, () => operations.refreshSource(source.id), { mayPrompt: true });
     output(`Refreshed Git Source: ${refreshed.id}\t${refreshed.url}`);
 }
 /** Runs the CLI application and returns a process exit code. */
-export async function runCli(argv = process.argv.slice(2), dependencies = {}) {
-    const output = dependencies.stdout ?? ((line) => console.log(line));
-    const errorOutput = dependencies.stderr ?? ((line) => console.error(line));
+export async function runCli(rawArgv = process.argv.slice(2), dependencies = {}) {
+    // A global flag, so every command's own option parser never sees it.
+    const verbose = rawArgv.includes("--verbose");
+    const argv = verbose ? rawArgv.filter((argument) => argument !== "--verbose") : rawArgv;
+    const progress = dependencies.progress ?? (dependencies.stderr === undefined ? createProgress({ verbose, tapChildOutput: withChildOutput }) : NO_PROGRESS);
+    // Every line is written after erasing any spinner, so a step that prints while it runs is never garbled.
+    const writeStdout = dependencies.stdout ?? ((line) => console.log(line));
+    const writeStderr = dependencies.stderr ?? ((line) => console.error(line));
+    const output = (line) => { progress.clear(); writeStdout(line); };
+    const errorOutput = (line) => { progress.clear(); writeStderr(line); };
     const operations = dependencies.operations ?? createSourceOperations({ homeDirectory: dependencies.homeDirectory });
     try {
         if (argv[0] === "--version" || argv[0] === "-v") {
@@ -201,7 +216,7 @@ export async function runCli(argv = process.argv.slice(2), dependencies = {}) {
         if (!command) {
             throw new CliUsageError(USAGE);
         }
-        return await command(argv.slice(1), { operations, dependencies, output });
+        return await command(argv.slice(1), { operations, dependencies, output, errorOutput, progress });
     }
     catch (error) {
         errorOutput(`Error: ${error instanceof Error ? error.message : "unknown error"}`);
@@ -210,7 +225,7 @@ export async function runCli(argv = process.argv.slice(2), dependencies = {}) {
 }
 /** Alias retained as a discoverable public CLI seam for embedding and tests. */
 export const main = runCli;
-async function runSourceRemoval(argv, operations, dependencies, output) {
+async function runSourceRemoval(argv, operations, dependencies, output, progress) {
     const options = parseRemoveSourceOptions(argv);
     const source = await findSource(operations, options.sourceId);
     if (source.kind === "builtin") {
@@ -232,17 +247,19 @@ async function runSourceRemoval(argv, operations, dependencies, output) {
         output(`  [${index}] ${selection.path} -> ${location}${selected.includes(selection) ? " (selected for removal)" : " (kept)"}`);
     }
     output("  Default: keep all dependent Skills tracked by default after Source removal");
-    const plan = await inspectSkillRemovals(selected, removalOptions, (selection, inspection) => {
+    const plan = await progress.run(`Inspecting ${selected.length} Skill${selected.length === 1 ? "" : "s"} for removal`, () => inspectSkillRemovals(selected, removalOptions, (selection, inspection) => {
         for (const line of describeSkillRemoval(selection, inspection, "Skill "))
             output(line);
-    });
+    }));
     assertNoOverlappingProjectSkillRemovalTargets(plan.inspections);
     requireConfirmation(options.confirmed, "Removal not confirmed; rerun with --yes after reviewing every Source and Skill preview");
     // Recheck every selected target before deleting the first one. A changed later
     // target must never result in a partially removed batch.
-    const rechecked = await recheckSkillRemoval(plan, removalOptions);
-    await removeSkillFiles(plan, rechecked, removalOptions);
-    await operations.removeGitSource(source.id, selected);
+    await progress.run("Removing Skill files", async () => {
+        const rechecked = await recheckSkillRemoval(plan, removalOptions);
+        await removeSkillFiles(plan, rechecked, removalOptions);
+    });
+    await progress.run(`Removing Git Source ${source.id}`, () => operations.removeGitSource(source.id, selected));
     output(`Removed Git Source: ${source.id}`);
     if (selected.length > 0) {
         output(`Removed ${selected.length} dependent user-global Skill${selected.length === 1 ? "" : "s"}; other dependent Skills remain tracked`);
@@ -418,7 +435,7 @@ function resolveRemovalSelections(dependent, requested) {
     }
     return Object.freeze(selected);
 }
-async function runSkillRemoval(argv, operations, dependencies, output) {
+async function runSkillRemoval(argv, operations, dependencies, output, progress) {
     const requested = [];
     const hosts = [];
     let confirmed = false;
@@ -446,7 +463,7 @@ async function runSkillRemoval(argv, operations, dependencies, output) {
     const selected = selectManagedSkills(installations, requested);
     const removalOptions = userGlobalRemovalOptions(path.resolve(dependencies.homeDirectory ?? homedir()), dependencies.installationOptions);
     if (hosts.length > 0) {
-        await runSkillHostRemoval(selected[0], hosts, installations, confirmed, operations, removalOptions, output);
+        await runSkillHostRemoval(selected[0], hosts, installations, confirmed, operations, removalOptions, output, progress);
         return;
     }
     output(`Preview: remove ${selected.length} user-global Skill${selected.length === 1 ? "" : "s"}`);
@@ -455,7 +472,7 @@ async function runSkillRemoval(argv, operations, dependencies, output) {
         output(line);
     output("  Installation records are reconciled after each successful Skill removal");
     requireConfirmation(confirmed, "Removal not confirmed; rerun with --yes after reviewing every Skill preview");
-    await executeSkillRemoval(plan, operations, removalOptions, installations);
+    await progress.run(`Removing ${selected.length} user-global Skill${selected.length === 1 ? "" : "s"}`, () => executeSkillRemoval(plan, operations, removalOptions, installations));
     output(`Removed ${selected.length} user-global Skill${selected.length === 1 ? "" : "s"}`);
 }
 /** Resolves `<id|path>` arguments to managed installations, reporting selection problems as usage errors. */
@@ -469,7 +486,7 @@ function selectManagedSkills(installations, requested) {
         throw error;
     }
 }
-async function runSkillHostRemoval(selection, hosts, installations, confirmed, operations, options, output) {
+async function runSkillHostRemoval(selection, hosts, installations, confirmed, operations, options, output, progress) {
     const plan = await planHostRemoval(selection, hosts, options).catch(rethrowSelectionError);
     output(plan.kind === "full"
         ? "Preview: remove 1 user-global Skill (every recorded Host is removed)"
@@ -478,12 +495,12 @@ async function runSkillHostRemoval(selection, hosts, installations, confirmed, o
         output(line);
     output("  The installation record is reconciled after the locations are removed");
     requireConfirmation(confirmed, "Removal not confirmed; rerun with --yes after reviewing the preview");
-    await executeHostRemoval(plan, operations, options, installations);
+    await progress.run(plan.kind === "full" ? "Removing 1 user-global Skill" : `Removing Hosts from ${selection.path}`, () => executeHostRemoval(plan, operations, options, installations));
     output(plan.kind === "full"
         ? "Removed 1 user-global Skill"
         : `Removed hosts ${plan.removed.join(", ")} from ${JSON.stringify(selection.path)}`);
 }
-async function runSkillHostAdd(argv, operations, dependencies, output) {
+async function runSkillHostAdd(argv, operations, dependencies, output, progress) {
     const requested = [];
     const hosts = [];
     let confirmed = false;
@@ -520,7 +537,7 @@ async function runSkillHostAdd(argv, operations, dependencies, output) {
         output(line);
     requireConfirmation(confirmed, "Host change not confirmed; rerun with --yes after reviewing the preview");
     requireConfirmation(confirmAdditionalHost, "Adding a Host exposes the installed Skill to more hosts; rerun with --yes --confirm-additional-host");
-    await executeHostAddition(plan, operations, options, installations, true);
+    await progress.run(`Adding Hosts to ${plan.selection.path}`, () => executeHostAddition(plan, operations, options, installations, true));
     output(`Added hosts ${plan.hosts.join(", ")} to ${JSON.stringify(plan.selection.path)}`);
 }
 function rethrowSelectionError(error) {
@@ -662,7 +679,7 @@ function outputUninstallSummary(options, removedManagedCount, output) {
         output("  npx/pnpm dlx runs need no uninstall (only a cache entry)");
     }
 }
-async function runUninstall(argv, operations, dependencies, output) {
+async function runUninstall(argv, operations, dependencies, output, progress) {
     const options = parseUninstallOptions(argv);
     assertUninstallCapabilities(options, operations);
     const homeDirectory = path.resolve(dependencies.homeDirectory ?? homedir());
@@ -685,7 +702,8 @@ async function runUninstall(argv, operations, dependencies, output) {
     if (options.skills || options.unmanagedSkills.length > 0 || options.data) {
         requireConfirmation(options.confirmed, "Uninstall not confirmed; rerun with --yes after reviewing every user-global deletion preview");
     }
-    const managedRechecked = await recheckSkillRemoval(managedPlan, removalOptions);
+    const recheckManaged = () => recheckSkillRemoval(managedPlan, removalOptions);
+    const managedRechecked = options.skills ? await progress.run("Rechecking Skills before removal", recheckManaged) : await recheckManaged();
     const rechecked = managedRechecked.inspections;
     const unmanagedRechecked = [];
     for (const inspection of unmanagedInspections) {
@@ -697,11 +715,13 @@ async function runUninstall(argv, operations, dependencies, output) {
     assertNoOverlappingUserGlobalSkillRemovals(unmanagedRechecked);
     assertNoManagedUnmanagedOverlap(rechecked, unmanagedRechecked, () => "An unmanaged Skill target changed into an overlap with a selected managed Skill; no path was changed");
     const expectedManagedInstallations = options.skills
-        ? await removeSkillsAndRecords(managedPlan, managedRechecked, operations, removalOptions, selectedInstallations)
+        ? await progress.run(`Removing ${selectedInstallations.length} managed Skill${selectedInstallations.length === 1 ? "" : "s"}`, () => removeSkillsAndRecords(managedPlan, managedRechecked, operations, removalOptions, selectedInstallations))
         : selectedInstallations;
-    await removeInspectedUnmanagedSkills(context, unmanagedInspections, expectedManagedInstallations);
+    if (unmanagedInspections.length > 0) {
+        await progress.run(`Removing ${unmanagedInspections.length} unmanaged Skill${unmanagedInspections.length === 1 ? "" : "s"}`, () => removeInspectedUnmanagedSkills(context, unmanagedInspections, expectedManagedInstallations));
+    }
     if (options.data) {
-        await operations.removeCatalogData();
+        await progress.run("Removing catalog data", () => operations.removeCatalogData());
     }
     outputUninstallSummary(options, selectedInstallations.length, output);
 }
@@ -717,13 +737,13 @@ function selfUpdateOperationsFor(dependencies) {
         packageRoot: path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../.."),
     });
 }
-async function runSelfUpdate(argv, dependencies, output) {
+async function runSelfUpdate(argv, dependencies, output, progress) {
     if (argv.length > 1 || (argv.length === 1 && argv[0] !== "--yes")) {
         throw new CliUsageError("Usage: agent-depot self update [--yes]");
     }
     const confirmed = argv[0] === "--yes";
     const selfUpdate = selfUpdateOperationsFor(dependencies);
-    const status = await selfUpdate.check();
+    const status = await progress.run("Checking for Agent Depot updates", () => selfUpdate.check());
     switch (status.kind) {
         case "unsupported":
             output(`Self-update is unavailable: ${status.reason}`);
@@ -744,7 +764,7 @@ async function runSelfUpdate(argv, dependencies, output) {
             output(`  command: npm install --global --no-audit --no-fund --no-update-notifier --logs-max=0 --ignore-scripts --registry=https://registry.npmjs.org/ ${AGENT_DEPOT_PACKAGE_NAME ?? "@iseoane/agent-depot"}@${status.latest}`);
             output("  npm package scripts will not run; no elevated privileges will be requested");
             requireConfirmation(confirmed, "Self-update not confirmed; rerun with --yes after reviewing the preview");
-            await selfUpdate.apply(status.latest);
+            await progress.run(`Updating Agent Depot to ${status.latest}`, () => selfUpdate.apply(status.latest));
             output(`Updated Agent Depot to ${status.latest}; restart the CLI to use the new version`);
             return 0;
         default: {
@@ -753,7 +773,7 @@ async function runSelfUpdate(argv, dependencies, output) {
         }
     }
 }
-async function runUpdate(argv, operations, dependencies, output) {
+async function runUpdate(argv, operations, dependencies, output, progress) {
     const options = parseUpdateOptions(argv);
     const apps = dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory });
     const packages = packageOperationsFor(dependencies, operations);
@@ -766,14 +786,14 @@ async function runUpdate(argv, operations, dependencies, output) {
     let packageCheckFailed = false;
     if (options.scope === "user-global") {
         try {
-            appUpdates = await checkAppUpdates(apps);
+            appUpdates = await progress.run("Checking App updates", () => checkAppUpdates(apps));
         }
         catch (error) {
             appCheckFailed = true;
             output(`Error (Apps): ${error instanceof Error ? error.message : String(error)}`);
         }
         try {
-            packageUpdates = await packages.checkUpdates(requestedPackages.length === 0 ? undefined : requestedPackages);
+            packageUpdates = await progress.run("Checking Package updates", () => packages.checkUpdates(requestedPackages.length === 0 ? undefined : requestedPackages));
         }
         catch (error) {
             packageCheckFailed = true;
@@ -782,7 +802,7 @@ async function runUpdate(argv, operations, dependencies, output) {
     }
     let loaded;
     try {
-        loaded = await loadUpdates({
+        loaded = await progress.run(`Checking ${options.scope} Skill updates`, () => loadUpdates({
             scope: options.scope,
             operations,
             ...(dependencies.homeDirectory === undefined ? {} : { homeDirectory: dependencies.homeDirectory }),
@@ -790,7 +810,7 @@ async function runUpdate(argv, operations, dependencies, output) {
             ...(dependencies.sourceAccess === undefined ? {} : { sourceAccess: dependencies.sourceAccess }),
             ...(dependencies.projectManifestStore === undefined ? {} : { projectManifestStore: dependencies.projectManifestStore }),
             ...(dependencies.installationOptions?.fileSystem === undefined ? {} : { installationFileSystem: dependencies.installationOptions.fileSystem }),
-        });
+        }));
     }
     catch (error) {
         output(`Error (Skills, ${options.scope}): ${error instanceof Error ? error.message : String(error)}`);
@@ -846,7 +866,7 @@ async function runUpdate(argv, operations, dependencies, output) {
     }
     for (const item of selectedPackages) {
         try {
-            const plan = await packages.planLifecycle(item.installed.selection, "update");
+            const plan = await planWithRefresh(packages, item.installed.selection, "update", progress);
             const approval = await packages.approvalStatus(item.installed.selection, "update");
             describeLifecyclePlan(plan, approval, output);
             if (approval === "approved") {
@@ -863,7 +883,9 @@ async function runUpdate(argv, operations, dependencies, output) {
         }
     }
     const selected = selectUpdateCandidates(assessment, options);
-    const { plans, failures: previewFailures, nonCanonicalPaths } = await previewUpdateCandidates(selected, context);
+    const { plans, failures: previewFailures, nonCanonicalPaths } = selected.length === 0
+        ? await previewUpdateCandidates(selected, context)
+        : await progress.run("Previewing Skill updates", () => previewUpdateCandidates(selected, context));
     // Successes and failures are reported in candidate order, as the preview runs.
     const failedIds = new Set(previewFailures.map(({ item }) => item.id));
     const plansById = new Map(plans.map((plan) => [plan.item.id, plan]));
@@ -882,7 +904,9 @@ async function runUpdate(argv, operations, dependencies, output) {
     const pathProblem = findPathConfirmationProblem(nonCanonicalPaths, options.confirmedPaths);
     if (pathProblem !== undefined)
         throw new CliUsageError(pathProblem);
-    const result = await applyConfirmedUpdates(selected, context, options.confirmedPaths);
+    const result = selected.length === 0
+        ? await applyConfirmedUpdates(selected, context, options.confirmedPaths)
+        : await progress.run(`Updating ${selected.length} Skill${selected.length === 1 ? "" : "s"}`, () => applyConfirmedUpdates(selected, context, options.confirmedPaths));
     for (const { item } of previewFailures) {
         if (!result.failed.some((failed) => failed.id === item.id)) {
             output(`Preview failure was not selected for application: ${JSON.stringify(item.id)}`);
@@ -897,7 +921,7 @@ async function runUpdate(argv, operations, dependencies, output) {
     let appUpdated = 0;
     for (const plan of appPlans) {
         try {
-            const outcome = await apps.executeLifecycle(plan, true);
+            const outcome = await progress.run(`Updating App ${plan.entry.recipe.name}`, () => apps.executeLifecycle(plan, true));
             output(`App ${plan.entry.recipe.name}: ${describeAppResult(outcome)}${outcome.reason ? `: ${outcome.reason}` : ""}`);
             if (outcome.status === "installed")
                 appUpdated++;
@@ -917,7 +941,7 @@ async function runUpdate(argv, operations, dependencies, output) {
     let packageUpdated = 0;
     for (const plan of packagePlans) {
         try {
-            const outcome = await packages.executeLifecycle(plan, true);
+            const outcome = await progress.run(`Updating Package ${formatPackageSelection(plan.selection)}`, () => packages.executeLifecycle(plan, true));
             output(`Package ${formatPackageSelection(plan.selection)}: ${describePackageResult(outcome)}`);
             if (outcome.status === "updated") {
                 packageUpdated++;
@@ -1097,16 +1121,16 @@ function outputUpdateItem(item, output) {
     const selection = item.selection;
     output(`  [${item.index}] ${item.id}${typeof selection?.path === "string" ? ` path=${selection.path}` : ""}: ${item.reason}`);
 }
-async function runInstall(argv, operations, dependencies, output) {
+async function runInstall(argv, operations, dependencies, output, progress) {
     const options = parseInstallOptions(argv);
     const sourceAccess = dependencies.sourceAccess ?? defaultProjectSkillTreeAccess();
     if (options.scope === "user-global") {
-        await runUserGlobalInstall(options, operations, dependencies, sourceAccess, output);
+        await runUserGlobalInstall(options, operations, dependencies, sourceAccess, output, progress);
         return;
     }
     const projectRoot = path.resolve(dependencies.projectRoot ?? process.cwd());
     const manifestStore = dependencies.projectManifestStore ?? new ProjectManifestStore(defaultProjectManifestPath(projectRoot));
-    const context = { options, operations, dependencies, sourceAccess, output, projectRoot, manifestStore };
+    const context = { options, operations, dependencies, sourceAccess, output, progress, projectRoot, manifestStore };
     if (options.fromManifest) {
         await runManifestInstall(context);
         return;
@@ -1114,7 +1138,7 @@ async function runInstall(argv, operations, dependencies, output) {
     await runSingleProjectInstall(context);
 }
 async function runManifestInstall(context) {
-    const { options, operations, dependencies, sourceAccess, output, projectRoot, manifestStore } = context;
+    const { options, operations, dependencies, sourceAccess, output, progress, projectRoot, manifestStore } = context;
     const manifest = await manifestStore.load();
     if (manifest.skills.length === 0) {
         throw new CliUsageError("The project manifest contains no selected Skills");
@@ -1141,7 +1165,7 @@ async function runManifestInstall(context) {
     if (skipped > 0) {
         output(`Skipped ${skipped} of ${manifest.skills.length} Skills pinned to another Agent Depot version`);
     }
-    const resolved = await resolveManifestSelections(installable, operations, sourceAccess, options.confirmed);
+    const resolved = await progress.run(`Resolving ${installable.length} manifest Skill${installable.length === 1 ? "" : "s"}`, () => resolveManifestSelections(installable, operations, sourceAccess, options.confirmed), { mayPrompt: options.confirmed && installable.some((selection) => selection.source.kind !== "builtin") });
     if (resolved.some((item) => item.method !== undefined) && resolved.length > 1) {
         throw new SourceMetadataError("A batch install containing an external method is refused because command side effects cannot be rolled back safely; install that Skill separately");
     }
@@ -1163,7 +1187,7 @@ async function runManifestInstall(context) {
     try {
         for (let index = 0; index < resolved.length; index += 1) {
             const item = resolved[index];
-            const transaction = await installOne(item.selection, item.source, sourceAccess, projectRoot, dependencies, item.method, options.portableV1, item.files, item.resolvedVersion, options.confirmAdditionalHostExposure, false, inspections[index]);
+            const transaction = await progress.run(`Installing ${item.selection.path}`, () => installOne(item.selection, item.source, sourceAccess, projectRoot, dependencies, item.method, options.portableV1, item.files, item.resolvedVersion, options.confirmAdditionalHostExposure, false, inspections[index]));
             if (transaction) {
                 transactions.push(transaction);
                 installed.push({ item, result: transaction.result });
@@ -1198,20 +1222,21 @@ async function runManifestInstall(context) {
     }
 }
 async function runSingleProjectInstall(context) {
-    const { options, operations, dependencies, sourceAccess, output, projectRoot, manifestStore } = context;
+    const { options, operations, dependencies, sourceAccess, output, progress, projectRoot, manifestStore } = context;
     if (!options.sourceId || !options.skillPath || !options.version || options.hosts.length === 0) {
         throw new CliUsageError(INSTALL_USAGE);
     }
     const existing = await manifestStore.load();
-    const plan = await planSingleInstall({ ...options, scope: "project", sourceId: options.sourceId, skillPath: options.skillPath, version: options.version }, { operations, sourceAccess, environment: dependencies, root: projectRoot, existing: existing.skills, recordedIn: manifestStore.path });
+    const request = { ...options, scope: "project", sourceId: options.sourceId, skillPath: options.skillPath, version: options.version };
+    const plan = await progress.run(`Resolving ${options.skillPath}`, () => planSingleInstall(request, { operations, sourceAccess, environment: dependencies, root: projectRoot, existing: existing.skills, recordedIn: manifestStore.path }), { mayPrompt: refreshesSource(options) });
     outputSingleInstallPreview(plan, output);
     requireConfirmation(options.confirmed, "Installation not confirmed; rerun with --yes to continue");
-    await executeSingleInstall(plan, async (record) => {
+    await progress.run(`Installing ${options.skillPath}`, () => executeSingleInstall(plan, async (record) => {
         await manifestStore.save(parseProjectManifest({ version: 1, skills: [...existing.skills, record] }));
-    }, output);
+    }, output));
     output(`Saved project manifest: ${manifestStore.path}`);
 }
-async function runUserGlobalInstall(options, operations, dependencies, sourceAccess, output) {
+async function runUserGlobalInstall(options, operations, dependencies, sourceAccess, output, progress) {
     if (options.fromManifest || !options.sourceId || !options.skillPath || !options.version || options.hosts.length === 0) {
         throw new CliUsageError(INSTALL_USAGE);
     }
@@ -1220,12 +1245,18 @@ async function runUserGlobalInstall(options, operations, dependencies, sourceAcc
         throw new Error("Configured Source operations cannot manage user-global installation state");
     }
     const homeDirectory = path.resolve(dependencies.homeDirectory ?? homedir());
-    const plan = await planSingleInstall({ ...options, scope: "user-global", sourceId: options.sourceId, skillPath: options.skillPath, version: options.version }, { operations, sourceAccess, environment: dependencies, root: homeDirectory, existing: await listUserGlobalInstallations.call(operations), recordedIn: "user-global state" });
+    const existing = await listUserGlobalInstallations.call(operations);
+    const request = { ...options, scope: "user-global", sourceId: options.sourceId, skillPath: options.skillPath, version: options.version };
+    const plan = await progress.run(`Resolving ${options.skillPath}`, () => planSingleInstall(request, { operations, sourceAccess, environment: dependencies, root: homeDirectory, existing, recordedIn: "user-global state" }), { mayPrompt: refreshesSource(options) });
     outputSingleInstallPreview(plan, output);
     requireConfirmation(options.confirmed, "Installation not confirmed; rerun with --yes to continue");
-    await executeSingleInstall(plan, (record) => addUserGlobalInstallation.call(operations, record), output);
+    await progress.run(`Installing ${options.skillPath}`, () => executeSingleInstall(plan, (record) => addUserGlobalInstallation.call(operations, record), output));
     output("Saved user-global installation state: shared Source state");
 }
+/** A confirmed install of a non-built-in Source refreshes it with `git`, which may ask for credentials. */
+function refreshesSource(options) {
+    return options.confirmed && options.sourceId !== BUILT_IN_SOURCE.id;
+}
 /** Appends the comma-separated `--host` value, rejecting unknown or repeated Hosts. */
 function collectHosts(hosts, value) {
     for (const host of value.split(",")) {

package/dist/src/executable-resolution.js

@@ -25,9 +25,15 @@ export function createPortableExecutableResolver(options = {}) {
             return { executable, blocked: target !== undefined && isWindowsExecutableOnWsl(target, wslEnvironment) };
         }
         let blockedExecutable;
-        const suffixes = platform === "win32"
-            ? ["", ...(process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")]
-            : [""];
+        // On Windows only PATHEXT candidates are runnable: npm installs an
+        // extensionless sh shim beside `name.cmd`, and spawning it fails (ENOENT).
+        const configuredExtensions = (process.env.PATHEXT ?? "").split(";").map((extension) => extension.trim()).filter(Boolean);
+        const extensions = configuredExtensions.length > 0 ? configuredExtensions : [".COM", ".EXE", ".BAT", ".CMD"];
+        const suffixes = platform !== "win32"
+            ? [""]
+            : extensions.some((extension) => name.toLowerCase().endsWith(extension.toLowerCase()))
+                ? [""]
+                : extensions;
         for (const directory of (process.env.PATH ?? "").split(path.delimiter)) {
             if (!path.isAbsolute(directory)) {
                 continue;

package/dist/src/git-source.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { lstat, mkdir, rename, rm, rmdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
+import { isLockContention } from "./atomic-file.js";
 import { assertNoSymlinkPath } from "./path-safety.js";
 import { runProcess } from "./process-runner.js";
 export const SKILL_TREE_LIMITS = Object.freeze({
@@ -424,7 +425,7 @@ async function acquireSourceLock(lockPath) {
             };
         }
         catch (error) {
-            if (!isAlreadyExists(error)) {
+            if (!isLockContention(error)) {
                 throw error;
             }
             if ((await pathType(lockPath)) === "symlink") {
@@ -481,9 +482,6 @@ function isSafeSourcePath(candidate) {
 function isMissing(error) {
     return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
-function isAlreadyExists(error) {
-    return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
-}
 const GIT_PROTOCOLS = new Set(["git:", "http:", "https:", "ssh:"]);
 export function canonicalizeGitSourceUrl(input) {
     if (typeof input !== "string" || input.length === 0 || input.trim() !== input) {

package/dist/src/package-cli.js

@@ -1,9 +1,10 @@
 import { sourceIdForUrl } from "./git-source.js";
 import { PACKAGE_HOSTS, bundleRoot, describeCoordinates, selectionKey } from "./package-model.js";
+import { NO_PROGRESS } from "./progress.js";
 import { projectSourceOf } from "./sources.js";
 import { CliUsageError } from "./usage-error.js";
 export const PACKAGE_USAGE = "Usage: agent-depot package list; package discover <source-id>; package inspect <selection> --host <host>; package approve <selection> --host <host> [--action <install|update|uninstall>]; package install|update|uninstall <selection> --host <host> [--yes]; package forget <selection> --host <host> --yes";
-export async function runPackageCommand(values, packages, sources, output) {
+export async function runPackageCommand(values, packages, sources, output, progress = NO_PROGRESS) {
     const [command, ...args] = values;
     if (command === "list") {
         requireNoArgs(args, "package list");
@@ -35,7 +36,7 @@ export async function runPackageCommand(values, packages, sources, output) {
             throw new CliUsageError("Package approval only applies to install, update, and uninstall actions");
         }
         const selection = await resolveSelection(parsed, packages, sources);
-        const plan = await packages.planLifecycle(selection, action);
+        const plan = await planWithRefresh(packages, selection, action, progress);
         describeLifecyclePlan(plan, await packages.approvalStatus(selection, action), output);
         await packages.approve(selection, action);
         output(`Approved Package ${action}: ${formatPackageSelection(selection)}`);
@@ -44,7 +45,7 @@ export async function runPackageCommand(values, packages, sources, output) {
     if (command === "install" || command === "update" || command === "uninstall") {
         const parsed = parseSelectionArgs(args, { allowConfirmation: true });
         const selection = await resolveSelection(parsed, packages, sources);
-        const plan = await packages.planLifecycle(selection, command);
+        const plan = await planWithRefresh(packages, selection, command, progress);
         const approval = await packages.approvalStatus(selection, command);
         describeLifecyclePlan(plan, approval, output);
         if (approval !== "approved") {
@@ -53,7 +54,7 @@ export async function runPackageCommand(values, packages, sources, output) {
         if (!parsed.confirmed) {
             throw new Error(`Package ${command} not confirmed; rerun with --yes after reviewing the preview`);
         }
-        const result = await packages.executeLifecycle(plan, true);
+        const result = await progress.run(`${command === "install" ? "Installing" : command === "update" ? "Updating" : "Uninstalling"} Package ${formatPackageSelection(selection)}`, () => packages.executeLifecycle(plan, true));
         output(`Package ${formatPackageSelection(selection)}: ${describePackageResult(result)}`);
         return packageResultSucceeded(result) ? 0 : 1;
     }
@@ -71,6 +72,10 @@ export async function runPackageCommand(values, packages, sources, output) {
     }
     throw new CliUsageError(PACKAGE_USAGE);
 }
+/** Planning refreshes the Package's Git Source (ADR 0004), and git may ask for credentials, so the step never animates. */
+export function planWithRefresh(packages, selection, action, progress) {
+    return progress.run(`Refreshing Source for Package ${formatPackageSelection(selection)}`, () => packages.planLifecycle(selection, action), { mayPrompt: true });
+}
 export function formatPackageSelection(selection) {
     return `${sourceToken(selection.source)}::${describeSelectionCoordinate(selection)}`;
 }

package/dist/src/package-flow.js

@@ -357,13 +357,14 @@ export function createPackageOperations(environment = {}) {
                     result = await runner(resolution.executable, command.args, {
                         cwd: plan.cwd,
                         captureStdout: true,
+                        streamStdout: true,
                         maxOutputBytes: PACKAGE_OUTPUT_LIMIT,
                         maxStderrBytes: PACKAGE_OUTPUT_LIMIT,
                     });
                 }
                 catch (error) {
                     const code = error?.code;
-                    if (code === undefined || !["ENOENT", "EACCES", "ENOEXEC", "EPERM"].includes(code)) {
+                    if (code === undefined || !["ENOENT", "EACCES", "ENOEXEC", "EPERM", "EINVAL"].includes(code)) {
                         throw error;
                     }
                     const detail = error instanceof Error ? error.message : String(error);