fix(skill): align dry-run exit codes and path preview

Author: hopelynd

packages/commands/src/commands/skill/add.ts

@@ -12,6 +12,7 @@ import {
   writeSkillLock,
 } from "bailian-cli-core";
 import { emitBare, emitResult, formatTable } from "bailian-cli-runtime";
+import { planFanoutLinks, summarizeAgents } from "./dry-run-plan.ts";
 
 interface AddOutcome {
   name: string;
@@ -57,26 +58,51 @@ export default defineCommand({
   exampleArgs: ["--all", "--name spark-video,bailian-model-recommend"],
   async run(ctx) {
     const format = ctx.settings.outputExplicit ? ctx.settings.output : "json";
-    const agents = detectInstalledAgents();
+    const index = await fetchSkillsIndex();
+    const remoteNames = Object.keys(index.skills);
     const parsed = ctx.flags.all ? "all" : parseSkillNames(ctx.flags.name, false);
+    const names = parsed === "all" ? remoteNames : parsed;
+    const agents = detectInstalledAgents();
 
     if (ctx.settings.dryRun) {
+      const skills = names.map((name) => {
+        const entry = index.skills[name];
+        if (!entry) {
+          return {
+            name,
+            status: "failed" as const,
+            reason: "skill not found in registry",
+          };
+        }
+        return {
+          name,
+          status: "install" as const,
+          publishedAt: entry.publishedAt,
+          links: planFanoutLinks(name, agents),
+        };
+      });
+
       emitResult(
         {
           action: "skill.add",
           registry: getSkillRegistryBaseUrl(),
-          agents: agents.map((agent) => agent.id),
-          skills: parsed,
+          agents: summarizeAgents(agents),
+          skills,
         },
         format,
       );
+
+      const failed = skills.filter((skill) => skill.status === "failed");
+      if (failed.length > 0) {
+        throw new BailianError(
+          `${failed.length}/${skills.length} skill(s) failed to install`,
+          ExitCode.GENERAL,
+          "Check the reason for failed skills in the output; network failures can be retried with bl skill add",
+        );
+      }
       return;
     }
 
-    const index = await fetchSkillsIndex();
-    const remoteNames = Object.keys(index.skills);
-    const names = parsed === "all" ? remoteNames : parsed;
-
     const lock = readSkillLock();
 
     // collect-then-throw: a single skill failure only affects itself; successful ones are written to disk and lock as usual.

packages/commands/src/commands/skill/dry-run-plan.ts

@@ -0,0 +1,54 @@
+import { existsSync, lstatSync } from "node:fs";
+import { join } from "node:path";
+import { getSkillsDir, type AgentTarget } from "bailian-cli-core";
+
+/** dry-run 用的 agent 摘要（含目标目录） */
+export function summarizeAgents(agents: AgentTarget[]): Array<{ id: string; skillsDir: string }> {
+  return agents.map((agent) => ({
+    id: agent.id,
+    skillsDir: agent.skillsDir,
+  }));
+}
+
+export type PathKind = "absent" | "symlink" | "directory" | "file";
+
+/** 预计 fan-out 路径及当前存在性（只读 lstat，不预测 replace/skip） */
+export interface PlannedLink {
+  agent: string;
+  path: string;
+  exists: boolean;
+  kind: PathKind;
+  hasSkillMd: boolean;
+}
+
+function inspectPath(path: string): Pick<PlannedLink, "exists" | "kind" | "hasSkillMd"> {
+  try {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) {
+      return { exists: true, kind: "symlink", hasSkillMd: false };
+    }
+    if (stat.isDirectory()) {
+      return {
+        exists: true,
+        kind: "directory",
+        hasSkillMd: existsSync(join(path, "SKILL.md")),
+      };
+    }
+    return { exists: true, kind: "file", hasSkillMd: false };
+  } catch {
+    return { exists: false, kind: "absent", hasSkillMd: false };
+  }
+}
+
+/** 按 agent skillsDir 拼出预计链接路径，并标注是否已存在 */
+export function planFanoutLinks(skillName: string, agents: AgentTarget[]): PlannedLink[] {
+  return agents.map((agent) => {
+    const path = join(agent.skillsDir, skillName);
+    return { agent: agent.id, path, ...inspectPath(path) };
+  });
+}
+
+/** Canonical skill 目录路径 */
+export function canonicalSkillPath(skillName: string): string {
+  return join(getSkillsDir(), skillName);
+}

packages/commands/src/commands/skill/init.ts

@@ -4,13 +4,13 @@ import {
   defineCommand,
   detectInstalledAgents,
   fetchSkillsIndex,
-  getSkillRegistryBaseUrl,
   installSkillWithFanout,
   readSkillLock,
   runWithConcurrency,
   writeSkillLock,
 } from "bailian-cli-core";
 import { emitBare, emitResult } from "bailian-cli-runtime";
+import { planFanoutLinks, summarizeAgents } from "./dry-run-plan.ts";
 
 /** Prefix used to identify first-party Bailian skills in the registry. */
 const BAILIAN_PREFIX = "bailian-";
@@ -55,26 +55,27 @@ export default defineCommand({
   ],
   async run(ctx) {
     const format = ctx.settings.outputExplicit ? ctx.settings.output : DEFAULT_FORMAT;
+    const index = await fetchSkillsIndex();
+
+    // Discover all bailian-* skills from the live registry index
+    const names = Object.keys(index.skills).filter((name) => name.startsWith(BAILIAN_PREFIX));
     const agents = detectInstalledAgents();
 
     if (ctx.settings.dryRun) {
       emitResult(
         {
           action: "skill.init",
-          registry: getSkillRegistryBaseUrl(),
-          skills: `${BAILIAN_PREFIX}*`,
-          agents: agents.map((agent) => agent.id),
+          skills: names.map((name) => ({
+            name,
+            links: planFanoutLinks(name, agents),
+          })),
+          agents: summarizeAgents(agents),
         },
         format,
       );
       return;
     }
 
-    const index = await fetchSkillsIndex();
-
-    // Discover all bailian-* skills from the live registry index
-    const names = Object.keys(index.skills).filter((name) => name.startsWith(BAILIAN_PREFIX));
-
     const lock = readSkillLock();
 
     const tasks = names.map((name) => async (): Promise<InitOutcome> => {

packages/commands/src/commands/skill/remove.ts

@@ -2,6 +2,7 @@ import {
   BailianError,
   ExitCode,
   defineCommand,
+  getSkillsDir,
   listSkillDirsOnDisk,
   parseSkillNames,
   readSkillLock,
@@ -10,6 +11,7 @@ import {
   writeSkillLock,
 } from "bailian-cli-core";
 import { emitBare, emitResult, formatTable } from "bailian-cli-runtime";
+import { join } from "node:path";
 
 interface RemoveOutcome {
   name: string;
@@ -18,6 +20,14 @@ interface RemoveOutcome {
   reason?: string;
 }
 
+interface RemovePlanItem {
+  name: string;
+  status: "remove" | "failed";
+  canonical?: string;
+  links?: string[];
+  reason?: string;
+}
+
 export default defineCommand({
   description: {
     "en-US": "Remove locally installed skills (registry is untouched)",
@@ -50,21 +60,42 @@ export default defineCommand({
       return;
     }
 
+    const diskDirs = new Set(listSkillDirsOnDisk());
+    const skillsDir = getSkillsDir();
+
     if (ctx.settings.dryRun) {
-      emitResult(
-        {
-          action: "skill.remove",
-          skills: names.map((name) => ({
+      const results: RemovePlanItem[] = names.map((name) => {
+        const locked = lock.skills[name];
+        if (!locked) {
+          return {
             name,
-            removedLinks: (lock.skills[name]?.links ?? []).length,
-          })),
-        },
-        format,
-      );
+            status: "failed",
+            reason: diskDirs.has(name)
+              ? "directory not managed by bl skill (untracked); remove manually if needed"
+              : "not installed",
+          };
+        }
+        return {
+          name,
+          status: "remove",
+          canonical: join(skillsDir, name),
+          links: locked.links ?? [],
+        };
+      });
+
+      emitResult({ action: "skill.remove", skills: results }, format);
+
+      const failed = results.filter((result) => result.status === "failed");
+      if (failed.length > 0) {
+        throw new BailianError(
+          `${failed.length}/${results.length} skill(s) failed to remove`,
+          ExitCode.GENERAL,
+          "Check the reason for failed skills in the output; use bl skill list to verify local install status",
+        );
+      }
       return;
     }
 
-    const diskDirs = new Set(listSkillDirsOnDisk());
     const results: RemoveOutcome[] = [];
     for (const name of names) {
       const locked = lock.skills[name];