skvlt 0.9.9

package/src/commands/backup.ts

@@ -0,0 +1,224 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import {
+  defaultManifestOptionPath,
+  defaultGlobalLockFilePath,
+} from "../internal/paths/defaults";
+import {
+  commandErrorPage,
+  helpExample,
+  helpFooter,
+  helpHeading,
+  infoLine,
+  summaryLine,
+  errorMessage,
+  page,
+} from "../internal/cli/theme";
+import { formatCliPath } from "../internal/paths/format-cli-path";
+import { parseBackupArgs } from "../internal/args/parse-backup-args";
+import { buildManifest } from "../internal/manifest/build-manifest";
+import type { LockFile } from "../internal/manifest/manifest-types";
+import { listInstalledSkillNames } from "../internal/process/list-installed-skill-names";
+
+export type BackupRunResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  errorCode?: string;
+  payload?: {
+    dryRun: boolean;
+    outputPath: string;
+    projectScope: boolean;
+    totalSkills: number;
+    totalSources: number;
+    manifest?: string;
+  };
+};
+
+export type BackupDependencies = {
+  getInstalledSkillNames?: (projectScope: boolean) => Promise<string[]>;
+  readLockFile?: (lockFilePath: string) => LockFile;
+  writeManifest?: (outputPath: string, manifest: string) => void;
+  reportProgress?: (chunk: string) => void;
+  streamOutput?: boolean;
+};
+
+function printHelp(): string {
+  return `\n${[
+    "Backup installed skills into skvlt.yaml.",
+    "",
+    helpHeading("Usage"),
+    "  bunx skvlt backup [options]",
+    "",
+    helpHeading("Options"),
+    "  --output <path>         Output path for skvlt.yaml",
+    "  --lock-file <path>      Skills lock file to read sources from",
+    "  --project-scope         Backup project-scoped installs instead of global installs",
+    "  --dry-run               Print YAML to stdout instead of writing a file",
+    "  --help                  Show this help",
+    "",
+    helpHeading("Notes"),
+    `  - Output defaults to: ${formatCliPath(defaultManifestOptionPath)}`,
+    `  - Global scope defaults to lock file: ${formatCliPath(defaultGlobalLockFilePath)}`,
+    "  - Project scope currently requires --lock-file because the Skills CLI does not expose a discoverable project lock path here.",
+    "",
+    helpHeading("Examples"),
+    helpExample("bunx skvlt backup"),
+    helpExample(`bunx skvlt backup --output ${formatCliPath("./skvlt.yaml")}`),
+    helpExample(
+      `bunx skvlt backup --project-scope --lock-file ${formatCliPath("./skills-lock.json")}`,
+    ),
+    helpFooter("https://github.com/xixu-me/skills-vault"),
+  ].join("\n")}`;
+}
+
+async function getInstalledSkillNames(
+  projectScope: boolean,
+): Promise<string[]> {
+  return listInstalledSkillNames(projectScope);
+}
+
+function readLockFile(lockFilePath: string): LockFile {
+  if (!existsSync(lockFilePath)) {
+    throw new Error(`Lock file not found: ${formatCliPath(lockFilePath)}`);
+  }
+
+  return JSON.parse(readFileSync(lockFilePath, "utf8")) as LockFile;
+}
+
+function resolveBackupErrorCode(message: string): string {
+  if (
+    message.startsWith("Unknown argument:") ||
+    message.includes("requires a path") ||
+    message.includes("--project-scope requires --lock-file")
+  ) {
+    return "INVALID_ARGUMENT";
+  }
+  if (message.startsWith("Lock file not found:")) {
+    return "LOCK_FILE_NOT_FOUND";
+  }
+  if (message.startsWith("Unable to list installed skills")) {
+    return "SKILLS_LIST_FAILED";
+  }
+
+  return "BACKUP_FAILED";
+}
+
+function formatBackupError(message: string, errorCode: string): string {
+  if (errorCode === "INVALID_ARGUMENT") {
+    return commandErrorPage(
+      message,
+      "bunx skvlt backup [options]",
+      `bunx skvlt backup --output ${formatCliPath("./skvlt.yaml")}`,
+    );
+  }
+
+  return page(errorMessage(message));
+}
+
+/**
+ * Captures the currently installed skills into a portable manifest snapshot.
+ */
+export async function runBackup(
+  argv: string[],
+  dependencies: BackupDependencies = {},
+): Promise<BackupRunResult> {
+  try {
+    const options = parseBackupArgs(argv);
+    if (options.help) {
+      return { exitCode: 0, stdout: printHelp(), stderr: "" };
+    }
+
+    const getInstalledSkillNamesImpl =
+      dependencies.getInstalledSkillNames ?? getInstalledSkillNames;
+    const readLockFileImpl = dependencies.readLockFile ?? readLockFile;
+    const writeManifestImpl = dependencies.writeManifest ?? writeFileSync;
+    const streamOutput = dependencies.streamOutput ?? false;
+    const reportProgress = dependencies.reportProgress ?? (() => {});
+    const outputLines: string[] = [];
+    let streamedOutput = false;
+    const appendLine = (line: string) => {
+      const formattedLine = line.includes("summary:")
+        ? summaryLine(line)
+        : infoLine(line);
+      if (streamOutput) {
+        if (!streamedOutput) {
+          reportProgress("\n");
+          streamedOutput = true;
+        }
+        reportProgress(`${formattedLine}\n`);
+        return;
+      }
+
+      outputLines.push(formattedLine);
+    };
+
+    appendLine("Listing installed skills...");
+    const installedSkillNames = await getInstalledSkillNamesImpl(
+      options.projectScope,
+    );
+    appendLine("Reading lock file metadata...");
+    const lockFile = readLockFileImpl(options.lockFilePath);
+    appendLine("Building manifest...");
+    // Persist the scope so restore can round-trip project/global installs.
+    const manifest = buildManifest(
+      installedSkillNames,
+      lockFile,
+      options.projectScope ? "project" : "global",
+    );
+
+    if (options.dryRun) {
+      return {
+        exitCode: 0,
+        stdout: manifest.yaml,
+        stderr: "",
+        payload: {
+          dryRun: true,
+          outputPath: options.outputPath,
+          projectScope: options.projectScope,
+          totalSkills: manifest.totalSkills,
+          totalSources: manifest.totalSources,
+          manifest: manifest.yaml,
+        },
+      };
+    }
+
+    appendLine(`Writing manifest to ${formatCliPath(options.outputPath)}...`);
+    const outputDirectoryPath = dirname(resolve(options.outputPath));
+    if (!existsSync(outputDirectoryPath)) {
+      mkdirSync(outputDirectoryPath, { recursive: true });
+    }
+    writeManifestImpl(options.outputPath, manifest.yaml);
+    appendLine(
+      `Backup summary: ${manifest.totalSkills} skill(s) across ${manifest.totalSources} source(s) written to ${formatCliPath(options.outputPath)}`,
+    );
+
+    return {
+      exitCode: 0,
+      stdout: streamOutput
+        ? streamedOutput
+          ? "\n"
+          : ""
+        : outputLines.length > 0
+          ? page(outputLines.join("\n"))
+          : "",
+      stderr: "",
+      payload: {
+        dryRun: false,
+        outputPath: options.outputPath,
+        projectScope: options.projectScope,
+        totalSkills: manifest.totalSkills,
+        totalSources: manifest.totalSources,
+      },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const errorCode = resolveBackupErrorCode(message);
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: formatBackupError(message, errorCode),
+      errorCode,
+    };
+  }
+}

package/src/commands/completion.ts

@@ -0,0 +1,197 @@
+import { parseCompletionArgs } from "../internal/args/parse-completion-args";
+import {
+  commandErrorPage,
+  errorMessage,
+  helpExample,
+  helpFooter,
+  helpHeading,
+  page,
+} from "../internal/cli/theme";
+
+export type CompletionRunResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  errorCode?: string;
+  payload?: {
+    shell: string;
+    script: string;
+  };
+};
+
+function printHelp(): string {
+  return `\n${[
+    "Print shell completion scripts for bunx skvlt.",
+    "",
+    helpHeading("Usage"),
+    "  bunx skvlt completion <bash|zsh|powershell>",
+    "",
+    helpHeading("Options"),
+    "  --help                 Show this help",
+    "",
+    helpHeading("Examples"),
+    helpExample("bunx skvlt completion bash"),
+    helpExample("bunx skvlt completion zsh"),
+    helpExample("bunx skvlt completion powershell"),
+    helpFooter("https://github.com/xixu-me/skills-vault"),
+  ].join("\n")}`;
+}
+
+function bashScript(): string {
+  return `# bash completion for skvlt
+_skvlt_completion() {
+  local current previous
+  current="\${COMP_WORDS[COMP_CWORD]}"
+  previous="\${COMP_WORDS[COMP_CWORD-1]}"
+  local commands="backup restore doctor completion"
+  local global_flags="--help --json --version"
+
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "$commands $global_flags" -- "$current") )
+    return 0
+  fi
+
+  case "\${COMP_WORDS[1]}" in
+    completion)
+      COMPREPLY=( $(compgen -W "bash zsh powershell --help" -- "$current") )
+      ;;
+    backup|restore|doctor)
+      COMPREPLY=( $(compgen -W "--help --json" -- "$current") )
+      ;;
+  esac
+}
+
+complete -F _skvlt_completion skvlt
+`;
+}
+
+function zshScript(): string {
+  return `#compdef skvlt
+
+_skvlt_completion() {
+  local -a commands
+  commands=(
+    'backup:Backup installed skills into a manifest'
+    'restore:Restore skills from a manifest'
+    'doctor:Inspect the local environment and skill state'
+    'completion:Print shell completion scripts'
+  )
+
+  _arguments \
+    '1:command:->command' \
+    '*::arg:->args'
+
+  case $state in
+    command)
+      _describe 'command' commands
+      ;;
+    args)
+      if [[ $words[2] == completion ]]; then
+        _values 'shell' bash zsh powershell
+      else
+        _values 'flag' --help --json --version
+      fi
+      ;;
+  esac
+}
+
+_skvlt_completion "$@"
+`;
+}
+
+function powershellScript(): string {
+  return `Register-ArgumentCompleter -Native -CommandName skvlt -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+
+  $commands = @('backup', 'restore', 'doctor', 'completion', '--help', '--json', '--version')
+  $completionText = $commandAst.CommandElements | ForEach-Object { $_.Extent.Text }
+
+  if ($completionText.Count -le 2) {
+    $commands |
+      Where-Object { $_ -like "$wordToComplete*" } |
+      ForEach-Object {
+        [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+      }
+    return
+  }
+
+  if ($completionText[1] -eq 'completion') {
+    @('bash', 'zsh', 'powershell') |
+      Where-Object { $_ -like "$wordToComplete*" } |
+      ForEach-Object {
+        [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+      }
+  }
+}
+`;
+}
+
+function buildCompletionScript(shell: string): string {
+  switch (shell) {
+    case "bash":
+      return bashScript();
+    case "zsh":
+      return zshScript();
+    case "powershell":
+      return powershellScript();
+    default:
+      throw new Error(`Unsupported shell: ${shell}`);
+  }
+}
+
+function resolveCompletionErrorCode(message: string): string {
+  if (
+    message.startsWith("Unsupported shell:") ||
+    message.startsWith("Unknown argument:")
+  ) {
+    return "INVALID_ARGUMENT";
+  }
+
+  return "COMPLETION_FAILED";
+}
+
+function formatCompletionError(message: string, errorCode: string): string {
+  if (errorCode === "INVALID_ARGUMENT") {
+    return commandErrorPage(
+      message,
+      "bunx skvlt completion <bash|zsh|powershell>",
+      "bunx skvlt completion bash",
+    );
+  }
+
+  return page(errorMessage(message));
+}
+
+/**
+ * Prints the requested shell completion script or top-level completion help.
+ */
+export async function runCompletion(
+  argv: string[],
+): Promise<CompletionRunResult> {
+  try {
+    const options = parseCompletionArgs(argv);
+    if (options.help || !options.shell) {
+      return { exitCode: 0, stdout: printHelp(), stderr: "" };
+    }
+
+    const script = buildCompletionScript(options.shell);
+    return {
+      exitCode: 0,
+      stdout: script,
+      stderr: "",
+      payload: {
+        shell: options.shell,
+        script,
+      },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const errorCode = resolveCompletionErrorCode(message);
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: formatCompletionError(message, errorCode),
+      errorCode,
+    };
+  }
+}

package/src/commands/doctor.ts

@@ -0,0 +1,257 @@
+import { existsSync } from "node:fs";
+import {
+  diffGlobalSkillState,
+  readInstalledGlobalSkillNames,
+  readTrackedGlobalSkillNames,
+} from "../internal/install/global-skill-state";
+import { BunxResult, runBunx } from "../internal/process/run-bunx";
+import { parseDoctorArgs } from "../internal/args/parse-doctor-args";
+import {
+  defaultGlobalLockFilePath,
+  defaultGlobalSkillsPath,
+} from "../internal/paths/defaults";
+import {
+  commandErrorPage,
+  errorMessage,
+  helpExample,
+  helpFooter,
+  helpHeading,
+  page,
+  statusTag,
+  summaryLine,
+} from "../internal/cli/theme";
+import { formatCliPath } from "../internal/paths/format-cli-path";
+
+type DoctorCheckStatus = "ok" | "warn" | "fail";
+
+type DoctorCheck = {
+  name: string;
+  status: DoctorCheckStatus;
+  detail: string;
+};
+
+export type DoctorRunResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  errorCode?: string;
+  payload?: {
+    manifestPath: string;
+    okCount: number;
+    warnCount: number;
+    failCount: number;
+    checks: DoctorCheck[];
+  };
+};
+
+export type DoctorDependencies = {
+  getBunVersion?: () => string;
+  checkSkillsCli?: () => Promise<{ ok: boolean; detail: string }>;
+  manifestExists?: (path: string) => boolean;
+  lockFileExists?: () => boolean;
+  skillsDirectoryExists?: () => boolean;
+  readTrackedGlobalSkillNames?: () => Promise<Set<string>>;
+  readInstalledGlobalSkillNames?: () => Promise<Set<string>>;
+};
+
+function printHelp(): string {
+  return `\n${[
+    "Inspect the local Skills Vault environment and installation state.",
+    "",
+    helpHeading("Usage"),
+    "  bunx skvlt doctor [options]",
+    "",
+    helpHeading("Options"),
+    "  --manifest <path>      Manifest path to inspect",
+    "  --help                 Show this help",
+    "",
+    helpHeading("Examples"),
+    helpExample("bunx skvlt doctor"),
+    helpExample("bunx skvlt doctor --manifest ./skvlt.yaml"),
+    helpFooter("https://github.com/xixu-me/skills-vault"),
+  ].join("\n")}`;
+}
+
+async function checkSkillsCli(): Promise<{ ok: boolean; detail: string }> {
+  const result: BunxResult = await runBunx(["skills", "--help"]);
+  if (result.exitCode !== 0) {
+    return {
+      ok: false,
+      detail: (result.stderr || result.stdout).trim() || "bunx skills failed",
+    };
+  }
+
+  return { ok: true, detail: "skills CLI available" };
+}
+
+function formatCheck(check: DoctorCheck) {
+  return `${statusTag(check.status)} ${check.name}: ${check.detail}`;
+}
+
+function summarizeChecks(checks: DoctorCheck[]) {
+  return checks.reduce(
+    (summary, check) => {
+      summary[`${check.status}Count` as const] += 1;
+      return summary;
+    },
+    {
+      okCount: 0,
+      warnCount: 0,
+      failCount: 0,
+    },
+  );
+}
+
+function formatDoctorError(message: string): string {
+  if (
+    message.startsWith("Unknown argument:") ||
+    message.includes("requires a value") ||
+    message.includes("requires a path")
+  ) {
+    return commandErrorPage(
+      message,
+      "bunx skvlt doctor [options]",
+      "bunx skvlt doctor --manifest ./skvlt.yaml",
+    );
+  }
+
+  return page(errorMessage(message));
+}
+
+/**
+ * Reports whether the local Bun, skills CLI, manifest, and global skill state look healthy.
+ */
+export async function runDoctor(
+  argv: string[],
+  dependencies: DoctorDependencies = {},
+): Promise<DoctorRunResult> {
+  try {
+    const options = parseDoctorArgs(argv);
+    if (options.help) {
+      return { exitCode: 0, stdout: printHelp(), stderr: "" };
+    }
+
+    const getBunVersion = dependencies.getBunVersion ?? (() => Bun.version);
+    const checkSkillsCliImpl = dependencies.checkSkillsCli ?? checkSkillsCli;
+    const manifestExists = dependencies.manifestExists ?? existsSync;
+    const lockFileExists =
+      dependencies.lockFileExists ??
+      (() => existsSync(defaultGlobalLockFilePath));
+    const skillsDirectoryExists =
+      dependencies.skillsDirectoryExists ??
+      (() => existsSync(defaultGlobalSkillsPath));
+    const readTrackedGlobalSkillNamesImpl =
+      dependencies.readTrackedGlobalSkillNames ?? readTrackedGlobalSkillNames;
+    const readInstalledGlobalSkillNamesImpl =
+      dependencies.readInstalledGlobalSkillNames ??
+      readInstalledGlobalSkillNames;
+
+    const checks: DoctorCheck[] = [];
+    checks.push({
+      name: "Bun runtime",
+      status: "ok",
+      detail: getBunVersion(),
+    });
+
+    const skillsCliStatus = await checkSkillsCliImpl();
+    checks.push({
+      name: "Skills CLI",
+      status: skillsCliStatus.ok ? "ok" : "fail",
+      detail: skillsCliStatus.detail,
+    });
+
+    checks.push({
+      name: "Manifest",
+      status: manifestExists(options.manifestPath) ? "ok" : "warn",
+      detail: manifestExists(options.manifestPath)
+        ? formatCliPath(options.manifestPath)
+        : `missing: ${formatCliPath(options.manifestPath)}`,
+    });
+
+    const hasLockFile = lockFileExists();
+    checks.push({
+      name: "Global lock file",
+      status: hasLockFile ? "ok" : "warn",
+      detail: hasLockFile
+        ? formatCliPath(defaultGlobalLockFilePath)
+        : `missing: ${formatCliPath(defaultGlobalLockFilePath)}`,
+    });
+
+    const hasSkillsDirectory = skillsDirectoryExists();
+    if (!hasSkillsDirectory) {
+      checks.push({
+        name: "Global skill state",
+        status: "warn",
+        detail: `skills directory missing: ${formatCliPath(defaultGlobalSkillsPath)}`,
+      });
+    } else if (!hasLockFile) {
+      checks.push({
+        name: "Global skill state",
+        status: "warn",
+        detail: "lock file missing; skipped consistency comparison",
+      });
+    } else {
+      const [trackedSkillNames, installedSkillNames] = await Promise.all([
+        readTrackedGlobalSkillNamesImpl(),
+        readInstalledGlobalSkillNamesImpl(),
+      ]);
+      // Report both mismatch directions so stale lock entries and missing lock
+      // entries show up as separate, actionable warnings.
+      const { missingFromLock, missingFromDirectory } = diffGlobalSkillState(
+        trackedSkillNames,
+        installedSkillNames,
+      );
+
+      checks.push({
+        name: "Global skill state",
+        status:
+          missingFromLock.length > 0 || missingFromDirectory.length > 0
+            ? "warn"
+            : "ok",
+        detail:
+          missingFromLock.length > 0 || missingFromDirectory.length > 0
+            ? [
+                missingFromLock.length > 0
+                  ? `${missingFromLock.length} installed missing from lock`
+                  : "",
+                missingFromDirectory.length > 0
+                  ? `${missingFromDirectory.length} tracked missing from skills directory`
+                  : "",
+              ]
+                .filter(Boolean)
+                .join("; ")
+            : `${installedSkillNames.size} installed / ${trackedSkillNames.size} tracked`,
+      });
+    }
+
+    const summary = summarizeChecks(checks);
+    const stdout = page(
+      [
+        ...checks.map(formatCheck),
+        summaryLine(
+          `Doctor summary: ${summary.okCount} ok, ${summary.warnCount} warn, ${summary.failCount} fail.`,
+        ),
+      ].join("\n"),
+    );
+
+    return {
+      exitCode: summary.failCount > 0 ? 1 : 0,
+      stdout,
+      stderr: "",
+      errorCode: summary.failCount > 0 ? "DOCTOR_FAILED" : undefined,
+      payload: {
+        manifestPath: options.manifestPath,
+        ...summary,
+        checks,
+      },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: formatDoctorError(message),
+      errorCode: "DOCTOR_FAILED",
+    };
+  }
+}