skvlt 0.9.9

package/src/internal/args/parse-backup-args.ts

@@ -0,0 +1,77 @@
+import {
+  defaultManifestOptionPath,
+  defaultGlobalLockFilePath,
+} from "../paths/defaults";
+
+export type BackupOptions = {
+  outputPath: string;
+  lockFilePath: string;
+  lockFileProvided: boolean;
+  projectScope: boolean;
+  dryRun: boolean;
+  help: boolean;
+};
+
+/**
+ * Parses backup CLI flags into a validated runtime options object.
+ */
+export function parseBackupArgs(argv: string[]): BackupOptions {
+  const options: BackupOptions = {
+    outputPath: defaultManifestOptionPath,
+    lockFilePath: defaultGlobalLockFilePath,
+    lockFileProvided: false,
+    projectScope: false,
+    dryRun: false,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    switch (arg) {
+      case "--output": {
+        const value = argv[index + 1];
+        if (!value || value.startsWith("-")) {
+          throw new Error("--output requires a path");
+        }
+        options.outputPath = value;
+        index += 1;
+        break;
+      }
+      case "--lock-file": {
+        const value = argv[index + 1];
+        if (!value || value.startsWith("-")) {
+          throw new Error("--lock-file requires a path");
+        }
+        options.lockFilePath = value;
+        options.lockFileProvided = true;
+        index += 1;
+        break;
+      }
+      case "--project-scope":
+        options.projectScope = true;
+        break;
+      case "--dry-run":
+        options.dryRun = true;
+        break;
+      case "--help":
+      case "-h":
+        options.help = true;
+        break;
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (options.help) {
+    return options;
+  }
+
+  if (options.projectScope && !options.lockFileProvided) {
+    throw new Error(
+      "--project-scope requires --lock-file because no project lock file could be auto-discovered in this workspace.",
+    );
+  }
+
+  return options;
+}

package/src/internal/args/parse-completion-args.ts

@@ -0,0 +1,30 @@
+export type CompletionOptions = {
+  shell?: string;
+  help: boolean;
+};
+
+/**
+ * Parses completion arguments while treating the first positional token as the shell.
+ */
+export function parseCompletionArgs(argv: string[]): CompletionOptions {
+  const options: CompletionOptions = {
+    shell: undefined,
+    help: false,
+  };
+
+  for (const arg of argv) {
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+
+    if (!options.shell) {
+      options.shell = arg;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return options;
+}

package/src/internal/args/parse-doctor-args.ts

@@ -0,0 +1,40 @@
+import { defaultManifestOptionPath } from "../paths/defaults";
+
+export type DoctorOptions = {
+  manifestPath: string;
+  help: boolean;
+};
+
+/**
+ * Parses doctor CLI flags into a manifest-aware diagnostics request.
+ */
+export function parseDoctorArgs(argv: string[]): DoctorOptions {
+  const options: DoctorOptions = {
+    manifestPath: defaultManifestOptionPath,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    switch (arg) {
+      case "--manifest": {
+        const value = argv[index + 1];
+        if (!value || value.startsWith("-")) {
+          throw new Error("--manifest requires a path");
+        }
+        options.manifestPath = value;
+        index += 1;
+        break;
+      }
+      case "--help":
+      case "-h":
+        options.help = true;
+        break;
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}

package/src/internal/args/parse-restore-args.ts

@@ -0,0 +1,119 @@
+import { defaultManifestOptionPath } from "../paths/defaults";
+
+export type RestoreOptions = {
+  manifestPath: string;
+  onlySources: string[];
+  agents: string[];
+  projectScope: boolean;
+  reinstallAll: boolean;
+  installAll: boolean;
+  copy: boolean;
+  continueOnError: boolean;
+  concurrency?: number;
+  dryRun: boolean;
+  help: boolean;
+};
+
+function parsePositiveIntegerOption(value: string, optionName: string): number {
+  if (!/^\d+$/.test(value)) {
+    throw new Error(`${optionName} requires a positive integer`);
+  }
+
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1) {
+    throw new Error(`${optionName} requires a positive integer`);
+  }
+
+  return parsed;
+}
+
+/**
+ * Parses restore CLI flags and keeps repeatable options in call order.
+ */
+export function parseRestoreArgs(argv: string[]): RestoreOptions {
+  const options: RestoreOptions = {
+    manifestPath: defaultManifestOptionPath,
+    onlySources: [],
+    agents: [],
+    projectScope: false,
+    reinstallAll: false,
+    installAll: false,
+    copy: false,
+    continueOnError: false,
+    concurrency: undefined,
+    dryRun: false,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    switch (arg) {
+      case "--manifest": {
+        const value = argv[index + 1];
+        if (!value || value.startsWith("-")) {
+          throw new Error("--manifest requires a path");
+        }
+        options.manifestPath = value;
+        index += 1;
+        break;
+      }
+      case "--only-source": {
+        const value = argv[index + 1];
+        if (!value || value.startsWith("-")) {
+          throw new Error("--only-source requires a value");
+        }
+        options.onlySources.push(value);
+        index += 1;
+        break;
+      }
+      case "--agent": {
+        const value = argv[index + 1];
+        if (!value || value.startsWith("-")) {
+          throw new Error("--agent requires a value");
+        }
+        options.agents.push(value);
+        index += 1;
+        break;
+      }
+      case "--project-scope":
+        options.projectScope = true;
+        break;
+      case "--reinstall-all":
+        options.reinstallAll = true;
+        break;
+      case "--all":
+        options.installAll = true;
+        break;
+      case "--copy":
+        options.copy = true;
+        break;
+      case "--continue-on-error":
+        options.continueOnError = true;
+        break;
+      case "--concurrency": {
+        const value = argv[index + 1];
+        if (!value || value.startsWith("-")) {
+          throw new Error("--concurrency requires a value");
+        }
+        options.concurrency = parsePositiveIntegerOption(
+          value,
+          "--concurrency",
+        );
+        index += 1;
+        break;
+      }
+      case "--dry-run":
+        options.dryRun = true;
+        break;
+      case "--help":
+      case "-h":
+        options.help = true;
+        break;
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}

package/src/internal/cli/theme.ts

@@ -0,0 +1,136 @@
+const reset = "\x1b[0m";
+const boldCode = "\x1b[1m";
+const dimCode = "\x1b[2m";
+const redCode = "\x1b[31m";
+const whiteCode = "\x1b[37m";
+const cyanCode = "\x1b[36m";
+const yellowCode = "\x1b[33m";
+const bgRedCode = "\x1b[41m";
+const dimGrayCode = "\x1b[38;5;102m";
+const textGrayCode = "\x1b[38;5;145m";
+const grayCode = "\x1b[38;5;245m";
+const grayDarkCode = "\x1b[38;5;238m";
+
+function wrap(text: string, ...codes: string[]) {
+  return `${codes.join("")}${text}${reset}`;
+}
+
+export function stripAnsi(text: string): string {
+  return text.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+export function bold(text: string): string {
+  return wrap(text, boldCode);
+}
+
+export function dim(text: string): string {
+  return wrap(text, dimCode);
+}
+
+export function red(text: string): string {
+  return wrap(text, redCode);
+}
+
+export function white(text: string): string {
+  return wrap(text, whiteCode);
+}
+
+export function cyan(text: string): string {
+  return wrap(text, cyanCode);
+}
+
+export function yellow(text: string): string {
+  return wrap(text, yellowCode);
+}
+
+export function dimGray(text: string): string {
+  return wrap(text, dimGrayCode);
+}
+
+export function textGray(text: string): string {
+  return wrap(text, textGrayCode);
+}
+
+export function gray(text: string): string {
+  return wrap(text, grayCode);
+}
+
+export function grayDark(text: string): string {
+  return wrap(text, grayDarkCode);
+}
+
+export function errorBadge(text: string): string {
+  return wrap(` ${text} `, bgRedCode, whiteCode, boldCode);
+}
+
+export function helpHeading(label: string): string {
+  return bold(`${label}:`);
+}
+
+export function helpExample(command: string, note?: string): string {
+  const suffix = note ? ` ${dimGray(`# ${note}`)}` : "";
+  return `  ${dimGray("$")} ${command}${suffix}`;
+}
+
+export function helpFooter(text: string): string {
+  return `\n${gray(`Explore the open-source repo at ${text}`)}\n\n`;
+}
+
+export function page(text: string): string {
+  const content = text.replace(/^\n+|\n+$/g, "");
+  return `\n${content}\n\n`;
+}
+
+export function commandErrorPage(
+  message: string,
+  usage: string,
+  example: string,
+): string {
+  return page(
+    [
+      `${errorBadge("ERROR")} ${red(message)}`,
+      "",
+      dim("  Usage:"),
+      `    ${usage}`,
+      "",
+      dim("  Example:"),
+      `    ${example}`,
+    ].join("\n"),
+  );
+}
+
+export function infoLine(text: string): string {
+  return text;
+}
+
+export function progressLine(
+  completed: number,
+  total: number,
+  label: string = "skills",
+): string {
+  const width = 10;
+  const safeTotal = Math.max(total, 1);
+  const safeCompleted = Math.min(Math.max(completed, 0), total);
+  const filled = Math.floor((safeCompleted / safeTotal) * width);
+  const bar = `[${"#".repeat(filled)}${"-".repeat(width - filled)}]`;
+  return `${grayDark("Progress:")} ${textGray(bar)} ${dimGray(`${safeCompleted}/${total} ${label}`)}`;
+}
+
+export function summaryLine(text: string): string {
+  return grayDark(text);
+}
+
+export function statusTag(status: "ok" | "warn" | "fail"): string {
+  switch (status) {
+    case "ok":
+      return grayDark("[ok]");
+    case "warn":
+      return gray("[warn]");
+    case "fail":
+      return red("[fail]");
+  }
+}
+
+export function errorMessage(text: string): string {
+  return red(text);
+}

package/src/internal/install/global-skill-state.ts

@@ -0,0 +1,102 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import {
+  defaultGlobalLockFilePath,
+  defaultGlobalSkillsPath,
+} from "../paths/defaults";
+
+export type GlobalSkillStateDiff = {
+  missingFromLock: string[];
+  missingFromDirectory: string[];
+};
+
+/**
+ * Reads the set of skill names tracked by the global lock file.
+ */
+export async function readTrackedGlobalSkillNames(
+  lockFilePath: string = defaultGlobalLockFilePath,
+): Promise<Set<string>> {
+  if (!existsSync(lockFilePath)) {
+    return new Set();
+  }
+
+  const lock = JSON.parse(readFileSync(lockFilePath, "utf8")) as {
+    skills?: Record<string, unknown>;
+  };
+
+  return new Set(Object.keys(lock.skills ?? {}).sort());
+}
+
+/**
+ * Reads the set of globally installed skill directories from disk.
+ */
+export async function readInstalledGlobalSkillNames(
+  skillsPath: string = defaultGlobalSkillsPath,
+): Promise<Set<string>> {
+  if (!existsSync(skillsPath)) {
+    return new Set();
+  }
+
+  return new Set(
+    readdirSync(skillsPath, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort(),
+  );
+}
+
+/**
+ * Compares tracked and installed global skills in both directions.
+ */
+export function diffGlobalSkillState(
+  trackedSkillNames: Set<string>,
+  installedSkillNames: Set<string>,
+): GlobalSkillStateDiff {
+  // Compare both directions so callers can distinguish "installed but
+  // untracked" from "tracked but missing on disk".
+  return {
+    missingFromLock: Array.from(installedSkillNames)
+      .filter((skillName) => !trackedSkillNames.has(skillName))
+      .sort((left, right) => left.localeCompare(right)),
+    missingFromDirectory: Array.from(trackedSkillNames)
+      .filter((skillName) => !installedSkillNames.has(skillName))
+      .sort((left, right) => left.localeCompare(right)),
+  };
+}
+
+/**
+ * Converts a global skill mismatch into short, user-facing diagnostics.
+ */
+export function formatGlobalSkillStateMismatch(
+  globalSkillStateDiff: GlobalSkillStateDiff,
+): string[] {
+  const mismatchLines: string[] = [];
+
+  // Compare both directions so restore cannot silently succeed with a stale lock.
+  if (globalSkillStateDiff.missingFromLock.length > 0) {
+    const preview = globalSkillStateDiff.missingFromLock
+      .slice(0, 10)
+      .join(", ");
+    const suffix =
+      globalSkillStateDiff.missingFromLock.length > 10 ? ", ..." : "";
+    mismatchLines.push(
+      `Global skills state mismatch: ${globalSkillStateDiff.missingFromLock.length} installed skill(s) missing from .skill-lock.json.`,
+    );
+    mismatchLines.push(`Missing tracked entries include: ${preview}${suffix}`);
+  }
+
+  if (globalSkillStateDiff.missingFromDirectory.length > 0) {
+    const preview = globalSkillStateDiff.missingFromDirectory
+      .slice(0, 10)
+      .join(", ");
+    const suffix =
+      globalSkillStateDiff.missingFromDirectory.length > 10 ? ", ..." : "";
+    mismatchLines.push(
+      `Global skills state mismatch: ${globalSkillStateDiff.missingFromDirectory.length} tracked skill(s) missing from the skills directory.`,
+    );
+    mismatchLines.push(
+      `Missing installed entries include: ${preview}${suffix}`,
+    );
+  }
+
+  return mismatchLines;
+}

package/src/internal/install/resolve-install-concurrency.ts

@@ -0,0 +1,74 @@
+import { availableParallelism } from "node:os";
+
+export type ResolveInstallConcurrencyOptions = {
+  configuredConcurrency?: number;
+  taskCount: number;
+  availableParallelism?: number;
+};
+
+const maxAutoConcurrency = 8;
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+function normalizeTaskCount(taskCount: number): number {
+  return Number.isFinite(taskCount) && taskCount > 0
+    ? Math.trunc(taskCount)
+    : 1;
+}
+
+function detectAvailableParallelism(): number {
+  try {
+    const detected = availableParallelism();
+    return Number.isFinite(detected) && detected > 0 ? detected : 1;
+  } catch {
+    return 1;
+  }
+}
+
+/**
+ * Parses a positive integer CLI flag that controls task concurrency.
+ */
+export function parsePositiveIntegerOption(
+  value: string,
+  optionName: string,
+): number {
+  if (!/^\d+$/.test(value)) {
+    throw new Error(`${optionName} requires a positive integer`);
+  }
+
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1) {
+    throw new Error(`${optionName} requires a positive integer`);
+  }
+
+  return parsed;
+}
+
+/**
+ * Chooses a safe install concurrency from user input, task count, and device capacity.
+ */
+export function resolveInstallConcurrency(
+  options: ResolveInstallConcurrencyOptions,
+): number {
+  const taskCount = normalizeTaskCount(options.taskCount);
+  const maxConcurrency = Math.min(taskCount, maxAutoConcurrency);
+
+  if (
+    typeof options.configuredConcurrency === "number" &&
+    Number.isFinite(options.configuredConcurrency)
+  ) {
+    return clamp(Math.trunc(options.configuredConcurrency), 1, taskCount);
+  }
+
+  const detectedParallelism =
+    typeof options.availableParallelism === "number" &&
+    Number.isFinite(options.availableParallelism) &&
+    options.availableParallelism > 0
+      ? options.availableParallelism
+      : detectAvailableParallelism();
+  const suggestedConcurrency = Math.ceil(detectedParallelism / 2);
+
+  return clamp(suggestedConcurrency, 1, maxConcurrency);
+}

package/src/internal/install/run-with-concurrency.ts

@@ -0,0 +1,72 @@
+export type ConcurrentFailure = {
+  index: number;
+  error: unknown;
+};
+
+export type RunWithConcurrencyOptions = {
+  continueOnError: boolean;
+};
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+function normalizeConcurrency(concurrency: number, taskCount: number): number {
+  const truncatedConcurrency = Math.trunc(concurrency);
+
+  if (!Number.isFinite(truncatedConcurrency)) {
+    return 1;
+  }
+
+  return clamp(truncatedConcurrency, 1, taskCount);
+}
+
+/**
+ * Executes async work items with a bounded worker pool and optional fail-fast behavior.
+ */
+export async function runWithConcurrency<T>(
+  items: T[],
+  concurrency: number,
+  worker: (item: T, index: number) => Promise<void>,
+  options: RunWithConcurrencyOptions,
+): Promise<ConcurrentFailure[]> {
+  if (items.length === 0) {
+    return [];
+  }
+
+  const failures: ConcurrentFailure[] = [];
+  let nextIndex = 0;
+  let firstError: unknown = null;
+  const workerCount = normalizeConcurrency(concurrency, items.length);
+
+  async function runWorker(): Promise<void> {
+    while (true) {
+      if (!options.continueOnError && firstError !== null) {
+        return;
+      }
+
+      const currentIndex = nextIndex;
+      if (currentIndex >= items.length) {
+        return;
+      }
+      nextIndex += 1;
+
+      try {
+        await worker(items[currentIndex] as T, currentIndex);
+      } catch (error: unknown) {
+        failures.push({ index: currentIndex, error });
+        if (!options.continueOnError && firstError === null) {
+          firstError = error;
+        }
+      }
+    }
+  }
+
+  await Promise.all(Array.from({ length: workerCount }, () => runWorker()));
+
+  if (!options.continueOnError && firstError !== null) {
+    throw firstError;
+  }
+
+  return failures;
+}

package/src/internal/install/skills-add-command.ts

@@ -0,0 +1,53 @@
+export type SkillsAddCommandOptions = {
+  agents: string[];
+  copy: boolean;
+  installAll: boolean;
+  projectScope: boolean;
+};
+
+function encodeShellArg(value: string): string {
+  if (/^[A-Za-z0-9_./:-]+$/.test(value)) {
+    return value;
+  }
+
+  return JSON.stringify(value);
+}
+
+/**
+ * Builds a `skills add` invocation that matches the selected restore mode.
+ */
+export function buildSkillsAddCommand(
+  source: string,
+  skills: string[],
+  options: SkillsAddCommandOptions,
+): string[] {
+  const command = ["skills", "add", source];
+  if (!options.projectScope) {
+    command.push("-g");
+  }
+
+  command.push("-y");
+
+  for (const agent of options.agents) {
+    command.push("--agent", agent);
+  }
+
+  if (options.copy) {
+    command.push("--copy");
+  }
+
+  if (options.installAll) {
+    command.push("--all");
+    return command;
+  }
+
+  command.push("--skill", ...skills);
+  return command;
+}
+
+/**
+ * Formats a command array into a shell-safe preview string for logs and dry-runs.
+ */
+export function formatCommandPreview(command: string[]): string {
+  return command.map(encodeShellArg).join(" ");
+}