skvlt 0.9.9

package/src/commands/restore.ts

@@ -0,0 +1,689 @@
+import { parseRestoreArgs } from "../internal/args/parse-restore-args";
+import {
+  diffGlobalSkillState,
+  formatGlobalSkillStateMismatch,
+  readInstalledGlobalSkillNames,
+  readTrackedGlobalSkillNames,
+  type GlobalSkillStateDiff,
+} from "../internal/install/global-skill-state";
+import { resolveInstallConcurrency } from "../internal/install/resolve-install-concurrency";
+import {
+  buildSkillsAddCommand,
+  formatCommandPreview,
+} from "../internal/install/skills-add-command";
+import {
+  runWithConcurrency,
+  type ConcurrentFailure,
+} from "../internal/install/run-with-concurrency";
+import { parseManifest } from "../internal/manifest/parse-manifest";
+import type { Manifest } from "../internal/manifest/manifest-types";
+import {
+  defaultManifestOptionPath,
+  defaultGlobalLockFilePath,
+  defaultGlobalSkillsPath,
+} from "../internal/paths/defaults";
+import {
+  commandErrorPage,
+  errorMessage,
+  helpExample,
+  helpFooter,
+  helpHeading,
+  infoLine,
+  page,
+  progressLine,
+  summaryLine,
+} from "../internal/cli/theme";
+import { formatCliPath } from "../internal/paths/format-cli-path";
+import { listInstalledSkillNames } from "../internal/process/list-installed-skill-names";
+import { runBunx, type BunxResult } from "../internal/process/run-bunx";
+
+type SourceRestoreEntry = {
+  source: string;
+  count: number;
+  skills: string[];
+  pendingSkills: string[];
+  alreadyInstalledSkills: string[];
+};
+
+export type RestoreRunResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  errorCode?: string;
+  payload?: {
+    manifestPath: string;
+    projectScope: boolean;
+    dryRun: boolean;
+    sourceCount: number;
+    requestedSkillTotal: number;
+    pendingSkillTotal: number;
+    installTaskCount: number;
+    continueOnError: boolean;
+  };
+};
+
+export type RestoreDependencies = {
+  readManifest?: (manifestPath: string) => Manifest;
+  getInstalledSkillNames?: (projectScope: boolean) => Promise<Set<string>>;
+  readTrackedGlobalSkillNames?: () => Promise<Set<string>>;
+  readInstalledGlobalSkillNames?: () => Promise<Set<string>>;
+  runBunx?: (args: string[]) => Promise<BunxResult>;
+  reportProgress?: (chunk: string) => void;
+  streamOutput?: boolean;
+};
+
+function printHelp(): string {
+  return `\n${[
+    "Restore skills from skvlt.yaml.",
+    "",
+    helpHeading("Usage"),
+    "  bunx skvlt restore [options]",
+    "",
+    helpHeading("Options"),
+    "  --manifest <path>        Path to skvlt.yaml",
+    "  --only-source <source>   Restore only one source; repeatable",
+    "  --agent <agent>          Target one agent; repeatable",
+    "  --project-scope          Restore to project scope instead of global",
+    "  --copy                   Copy files instead of symlinking to agent directories",
+    "  --all                    Install all skills from the selected sources",
+    "  --reinstall-all          Reinstall everything instead of only missing skills",
+    "  --continue-on-error      Keep going if one source fails to install",
+    "  --concurrency <count>    Maximum sources to install at the same time",
+    "  --dry-run                Print manifest-derived bunx commands without running them",
+    "  --help                   Show this help",
+    "",
+    helpHeading("Notes"),
+    `  - Manifest defaults to: ${formatCliPath(defaultManifestOptionPath)}`,
+    "  - Restore scope defaults to the scope recorded in the manifest; --project-scope overrides it to project scope.",
+    `  - Global restore verifies ${formatCliPath(defaultGlobalSkillsPath)} against ${formatCliPath(defaultGlobalLockFilePath)}`,
+    "",
+    helpHeading("Examples"),
+    helpExample("bunx skvlt restore --only-source xixu-me/skills"),
+    helpExample("bunx skvlt restore --all"),
+    helpExample("bunx skvlt restore --project-scope --manifest ./skvlt.yaml"),
+    helpFooter("https://github.com/xixu-me/skills-vault"),
+  ].join("\n")}`;
+}
+
+async function getInstalledSkillNames(
+  projectScope: boolean,
+): Promise<Set<string>> {
+  return new Set(await listInstalledSkillNames(projectScope));
+}
+
+function resolveRestoreErrorCode(message: string): string {
+  if (
+    message.startsWith("Unknown argument:") ||
+    message.includes("requires a value") ||
+    message.includes("requires a path") ||
+    message.includes("requires a positive integer")
+  ) {
+    return "INVALID_ARGUMENT";
+  }
+  if (message.startsWith("Manifest not found:")) {
+    return "MANIFEST_NOT_FOUND";
+  }
+  if (message.startsWith("Requested source(s) not found in manifest:")) {
+    return "SOURCE_NOT_FOUND";
+  }
+  if (message.startsWith("Unable to list installed skills")) {
+    return "SKILLS_LIST_FAILED";
+  }
+  if (message.startsWith("Install failed for source")) {
+    return "INSTALL_FAILED";
+  }
+  if (message.startsWith("Global skills state mismatch:")) {
+    return "GLOBAL_STATE_MISMATCH";
+  }
+
+  return "RESTORE_FAILED";
+}
+
+function formatRestoreError(message: string, errorCode: string): string {
+  if (errorCode === "INVALID_ARGUMENT") {
+    return commandErrorPage(
+      message,
+      "bunx skvlt restore [options]",
+      "bunx skvlt restore --all",
+    );
+  }
+
+  return page(errorMessage(message));
+}
+
+function selectSources(
+  manifest: Manifest,
+  onlySources: string[],
+): SourceRestoreEntry[] {
+  const entries: SourceRestoreEntry[] = Array.from(
+    manifest.sources.entries(),
+  ).map(([source, entry]) => ({
+    source,
+    count: entry.count,
+    skills: [...entry.skills],
+    pendingSkills: [],
+    alreadyInstalledSkills: [],
+  }));
+
+  if (onlySources.length === 0) {
+    return entries;
+  }
+
+  const selected = entries.filter((entry) =>
+    onlySources.includes(entry.source),
+  );
+  const selectedSources = new Set(selected.map((entry) => entry.source));
+  const missing = onlySources.filter((source) => !selectedSources.has(source));
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Requested source(s) not found in manifest: ${missing.join(", ")}`,
+    );
+  }
+
+  return selected;
+}
+
+async function verifyGlobalSkillStateConsistency(
+  dependencies: Required<RestoreDependencies>,
+): Promise<GlobalSkillStateDiff> {
+  const [trackedSkillNames, installedSkillNames] = await Promise.all([
+    dependencies.readTrackedGlobalSkillNames(),
+    dependencies.readInstalledGlobalSkillNames(),
+  ]);
+
+  return diffGlobalSkillState(trackedSkillNames, installedSkillNames);
+}
+
+function buildRestoreSummary(
+  sourceCount: number,
+  installTaskCount: number,
+  summarySkillTotal: number,
+  installAll: boolean,
+): string {
+  if (installAll) {
+    return `Restore summary: ${sourceCount} source(s) processed, ${installTaskCount} source install(s) attempted, upstream source state determined the installed skill count.`;
+  }
+
+  return `Restore summary: ${sourceCount} source(s) processed, ${installTaskCount} source install(s) attempted, ${summarySkillTotal} skill(s) scheduled.`;
+}
+
+async function runRestoreFromManifest(
+  manifest: Manifest,
+  manifestPath: string,
+  options: ReturnType<typeof parseRestoreArgs>,
+  dependencies: Required<RestoreDependencies>,
+): Promise<RestoreRunResult> {
+  const lines: string[] = [];
+  const errors: string[] = [];
+  const streamOutput = dependencies.streamOutput;
+  const reportProgress = dependencies.reportProgress;
+  let streamedOutput = false;
+  const emitStreamLine = (line: string) => {
+    if (!streamedOutput) {
+      reportProgress("\n");
+      streamedOutput = true;
+    }
+    reportProgress(`${line}\n`);
+  };
+  const appendLine = (line: string) => {
+    const formattedLine = line.includes("summary:")
+      ? summaryLine(line)
+      : infoLine(line);
+    if (streamOutput) {
+      emitStreamLine(formattedLine);
+      return;
+    }
+
+    lines.push(formattedLine);
+  };
+  const entries = selectSources(manifest, options.onlySources);
+  const requestedSkillTotal = entries.reduce(
+    (sum, entry) => sum + entry.count,
+    0,
+  );
+  // The manifest becomes the source of truth for scope unless the user forces
+  // project scope on the command line.
+  const projectScope = options.projectScope || manifest.scope === "project";
+  const scopeLabel = projectScope ? "project" : "global";
+
+  if (options.dryRun) {
+    const previewConcurrency = resolveInstallConcurrency({
+      configuredConcurrency: options.concurrency,
+      taskCount: entries.length,
+    });
+
+    appendLine(
+      `Previewing ${requestedSkillTotal} skill(s) from ${entries.length} source(s) using '${scopeLabel}' scope.`,
+    );
+    appendLine(
+      `Parallel install concurrency: ${previewConcurrency}${options.concurrency ? " (configured)" : " (auto)"}.`,
+    );
+    if (options.installAll) {
+      // `skills add --all` delegates skill selection to the upstream source, so
+      // it is intentionally broader than the manifest snapshot.
+      appendLine(
+        "Manifest skill selections are ignored when --all is enabled; upstream source state determines what gets installed.",
+      );
+    } else {
+      appendLine(
+        "Dry run does not inspect locally installed skills; commands include every skill listed in the manifest.",
+      );
+    }
+
+    for (const entry of entries) {
+      const preview = formatCommandPreview([
+        "bunx",
+        ...buildSkillsAddCommand(entry.source, entry.skills, {
+          ...options,
+          projectScope,
+        }),
+      ]);
+      appendLine(`[dry-run] ${preview}`);
+    }
+
+    return {
+      exitCode: 0,
+      stdout: streamOutput
+        ? streamedOutput
+          ? "\n"
+          : ""
+        : page(lines.join("\n")),
+      stderr: "",
+      payload: {
+        manifestPath,
+        projectScope,
+        dryRun: true,
+        sourceCount: entries.length,
+        requestedSkillTotal,
+        pendingSkillTotal: requestedSkillTotal,
+        installTaskCount: entries.length,
+        continueOnError: options.continueOnError,
+      },
+    };
+  }
+
+  const installedLookup = options.installAll
+    ? null
+    : await dependencies.getInstalledSkillNames(projectScope);
+  const showSkillProgress = streamOutput && !options.installAll;
+  let pendingSkillTotal = 0;
+  let alreadyInstalledTotal = 0;
+  const scheduledSkillTotal =
+    options.installAll || options.reinstallAll ? requestedSkillTotal : 0;
+  const installTasks: Array<{
+    order: number;
+    entry: SourceRestoreEntry;
+    skillsToInstall: string[];
+    command: string[];
+  }> = [];
+  appendLine(`Loading manifest from ${formatCliPath(manifestPath)}...`);
+  appendLine("Planning restore operations...");
+
+  for (const [index, entry] of entries.entries()) {
+    if (options.installAll) {
+      appendLine(
+        `Source ${index + 1}/${entries.length}: ${entry.source} (manifest lists ${entry.count} skill(s); --all delegates selection upstream).`,
+      );
+      installTasks.push({
+        order: index + 1,
+        entry,
+        skillsToInstall: [],
+        command: buildSkillsAddCommand(entry.source, entry.skills, {
+          ...options,
+          projectScope,
+        }),
+      });
+      continue;
+    }
+
+    if (options.reinstallAll) {
+      entry.pendingSkills = [...entry.skills];
+      pendingSkillTotal += entry.count;
+      appendLine(
+        `Source ${index + 1}/${entries.length}: ${entry.source} (${entry.pendingSkills.length} skill(s) selected via --reinstall-all).`,
+      );
+      installTasks.push({
+        order: index + 1,
+        entry,
+        skillsToInstall: [...entry.skills],
+        command: buildSkillsAddCommand(entry.source, entry.skills, {
+          ...options,
+          projectScope,
+        }),
+      });
+      continue;
+    }
+
+    entry.pendingSkills = entry.skills.filter(
+      (skill) => !installedLookup!.has(skill),
+    );
+    entry.alreadyInstalledSkills = entry.skills.filter((skill) =>
+      installedLookup!.has(skill),
+    );
+    pendingSkillTotal += entry.pendingSkills.length;
+    alreadyInstalledTotal += entry.alreadyInstalledSkills.length;
+    appendLine(
+      `Source ${index + 1}/${entries.length}: ${entry.source} (${entry.pendingSkills.length} pending, ${entry.alreadyInstalledSkills.length} already installed).`,
+    );
+
+    if (entry.pendingSkills.length > 0) {
+      installTasks.push({
+        order: index + 1,
+        entry,
+        skillsToInstall: [...entry.pendingSkills],
+        command: buildSkillsAddCommand(entry.source, entry.pendingSkills, {
+          ...options,
+          projectScope,
+        }),
+      });
+    }
+  }
+
+  if (options.installAll) {
+    appendLine(
+      `Installing all skills from ${entries.length} source(s) using '${scopeLabel}' scope.`,
+    );
+    appendLine(
+      "Manifest skill selections are ignored when --all is enabled; upstream source state determines what gets installed.",
+    );
+  } else if (options.reinstallAll) {
+    appendLine(
+      `Reinstalling ${requestedSkillTotal} skill(s) from ${entries.length} source(s) using '${scopeLabel}' scope.`,
+    );
+  } else {
+    appendLine(
+      `Restoring up to ${requestedSkillTotal} skill(s) from ${entries.length} source(s) using '${scopeLabel}' scope.`,
+    );
+    appendLine(
+      `${pendingSkillTotal} pending, ${alreadyInstalledTotal} already installed.`,
+    );
+  }
+
+  for (const entry of entries) {
+    if (
+      !options.installAll &&
+      !options.reinstallAll &&
+      entry.pendingSkills.length === 0
+    ) {
+      appendLine(
+        `Skipping ${entry.source}: all ${entry.count} skill(s) already installed.`,
+      );
+    }
+  }
+
+  if (installTasks.length === 0) {
+    if (!projectScope) {
+      const globalSkillStateDiff =
+        await verifyGlobalSkillStateConsistency(dependencies);
+      if (
+        globalSkillStateDiff.missingFromLock.length > 0 ||
+        globalSkillStateDiff.missingFromDirectory.length > 0
+      ) {
+        return {
+          exitCode: 1,
+          stdout: streamOutput
+            ? streamedOutput
+              ? "\n"
+              : ""
+            : page(lines.join("\n")),
+          stderr: page(
+            formatGlobalSkillStateMismatch(globalSkillStateDiff)
+              .map((line) => errorMessage(line))
+              .join("\n"),
+          ),
+          errorCode: "GLOBAL_STATE_MISMATCH",
+        };
+      }
+    }
+
+    appendLine(
+      `Restore summary: ${entries.length} source(s) processed, 0 source install(s) attempted, 0 skill(s) scheduled.`,
+    );
+    return {
+      exitCode: 0,
+      stdout: streamOutput
+        ? streamedOutput
+          ? "\n"
+          : ""
+        : page(lines.join("\n")),
+      stderr: "",
+      payload: {
+        manifestPath,
+        projectScope,
+        dryRun: false,
+        sourceCount: entries.length,
+        requestedSkillTotal,
+        pendingSkillTotal: 0,
+        installTaskCount: 0,
+        continueOnError: options.continueOnError,
+      },
+    };
+  }
+
+  // The Skills CLI mutates a shared global lock file, so live installs stay
+  // serialized even when dry-run previews show a higher theoretical limit.
+  const concurrency = 1;
+  appendLine(
+    `Installing from ${installTasks.length} source(s) with concurrency ${concurrency} (lock-safe mode).`,
+  );
+  const totalProgressSkills = options.reinstallAll
+    ? requestedSkillTotal
+    : pendingSkillTotal;
+  let completedProgressSkills = 0;
+  if (showSkillProgress && totalProgressSkills > 0) {
+    emitStreamLine(progressLine(0, totalProgressSkills));
+  }
+
+  let failures: ConcurrentFailure[] = [];
+
+  try {
+    failures = await runWithConcurrency(
+      installTasks,
+      concurrency,
+      async (task) => {
+        appendLine(
+          `Installing source ${task.order}/${entries.length}: ${task.entry.source}`,
+        );
+        if (options.installAll) {
+          appendLine(
+            `Installing all skills from ${task.entry.source} via --all...`,
+          );
+        } else if (
+          !options.reinstallAll &&
+          task.entry.alreadyInstalledSkills.length > 0
+        ) {
+          appendLine(
+            `Installing ${task.skillsToInstall.length} missing skill(s) from ${task.entry.source} and skipping ${task.entry.alreadyInstalledSkills.length} already installed.`,
+          );
+        } else {
+          appendLine(
+            `Installing ${task.skillsToInstall.length} skill(s) from ${task.entry.source}...`,
+          );
+        }
+
+        const result = await dependencies.runBunx(task.command);
+        if (result.stdout.trim()) {
+          appendLine(result.stdout.trimEnd());
+        }
+        if (result.stderr.trim()) {
+          errors.push(errorMessage(result.stderr.trimEnd()));
+        }
+
+        if (showSkillProgress && totalProgressSkills > 0) {
+          completedProgressSkills += task.skillsToInstall.length;
+          emitStreamLine(
+            progressLine(completedProgressSkills, totalProgressSkills),
+          );
+        }
+
+        if (result.exitCode !== 0) {
+          const message = `Install failed for source '${task.entry.source}' with exit code ${result.exitCode}`;
+          if (options.continueOnError) {
+            errors.push(message);
+          }
+          throw new Error(message);
+        }
+      },
+      { continueOnError: options.continueOnError },
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      exitCode: 1,
+      stdout: streamOutput
+        ? streamedOutput
+          ? "\n"
+          : ""
+        : lines.length > 0
+          ? page(lines.join("\n"))
+          : "",
+      stderr: page([...errors, errorMessage(message)].join("\n")),
+      errorCode: resolveRestoreErrorCode(message),
+    };
+  }
+
+  const summarySkillTotal =
+    options.installAll || options.reinstallAll
+      ? scheduledSkillTotal
+      : pendingSkillTotal;
+
+  if (options.continueOnError && failures.length > 0) {
+    appendLine(
+      buildRestoreSummary(
+        entries.length,
+        installTasks.length,
+        summarySkillTotal,
+        options.installAll,
+      ),
+    );
+    errors.push(
+      errorMessage(
+        `Completed restore with ${failures.length} source failure(s).`,
+      ),
+    );
+    return {
+      exitCode: 0,
+      stdout: streamOutput
+        ? streamedOutput
+          ? "\n"
+          : ""
+        : lines.length > 0
+          ? page(lines.join("\n"))
+          : "",
+      stderr: page(errors.join("\n")),
+      payload: {
+        manifestPath,
+        projectScope,
+        dryRun: false,
+        sourceCount: entries.length,
+        requestedSkillTotal,
+        pendingSkillTotal: summarySkillTotal,
+        installTaskCount: installTasks.length,
+        continueOnError: options.continueOnError,
+      },
+    };
+  }
+
+  if (!projectScope) {
+    const globalSkillStateDiff =
+      await verifyGlobalSkillStateConsistency(dependencies);
+    if (
+      globalSkillStateDiff.missingFromLock.length > 0 ||
+      globalSkillStateDiff.missingFromDirectory.length > 0
+    ) {
+      return {
+        exitCode: 1,
+        stdout: streamOutput
+          ? streamedOutput
+            ? "\n"
+            : ""
+          : lines.length > 0
+            ? page(lines.join("\n"))
+            : "",
+        stderr: page(
+          formatGlobalSkillStateMismatch(globalSkillStateDiff)
+            .map((line) => errorMessage(line))
+            .join("\n"),
+        ),
+        errorCode: "GLOBAL_STATE_MISMATCH",
+      };
+    }
+  }
+
+  appendLine(
+    buildRestoreSummary(
+      entries.length,
+      installTasks.length,
+      summarySkillTotal,
+      options.installAll,
+    ),
+  );
+  return {
+    exitCode: 0,
+    stdout: streamOutput
+      ? streamedOutput
+        ? "\n"
+        : ""
+      : lines.length > 0
+        ? page(lines.join("\n"))
+        : "",
+    stderr: errors.length > 0 ? page(errors.join("\n")) : "",
+    payload: {
+      manifestPath,
+      projectScope,
+      dryRun: false,
+      sourceCount: entries.length,
+      requestedSkillTotal,
+      pendingSkillTotal: summarySkillTotal,
+      installTaskCount: installTasks.length,
+      continueOnError: options.continueOnError,
+    },
+  };
+}
+
+/**
+ * Restores skills from a manifest while preserving the manifest's scope by default.
+ */
+export async function runRestore(
+  argv: string[],
+  dependencies: RestoreDependencies = {},
+): Promise<RestoreRunResult> {
+  try {
+    const options = parseRestoreArgs(argv);
+    if (options.help) {
+      return { exitCode: 0, stdout: printHelp(), stderr: "" };
+    }
+
+    const resolvedDependencies: Required<RestoreDependencies> = {
+      readManifest: dependencies.readManifest ?? parseManifest,
+      getInstalledSkillNames:
+        dependencies.getInstalledSkillNames ?? getInstalledSkillNames,
+      readTrackedGlobalSkillNames:
+        dependencies.readTrackedGlobalSkillNames ?? readTrackedGlobalSkillNames,
+      readInstalledGlobalSkillNames:
+        dependencies.readInstalledGlobalSkillNames ??
+        readInstalledGlobalSkillNames,
+      runBunx: dependencies.runBunx ?? runBunx,
+      reportProgress: dependencies.reportProgress ?? (() => {}),
+      streamOutput: dependencies.streamOutput ?? false,
+    };
+
+    const manifest = resolvedDependencies.readManifest(options.manifestPath);
+    return runRestoreFromManifest(
+      manifest,
+      options.manifestPath,
+      options,
+      resolvedDependencies,
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const errorCode = resolveRestoreErrorCode(message);
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: formatRestoreError(message, errorCode),
+      errorCode,
+    };
+  }
+}