skvlt 0.9.9

package/src/internal/manifest/build-manifest.ts

@@ -0,0 +1,78 @@
+import type {
+  LockFile,
+  ManifestBuildResult,
+  ManifestScope,
+} from "./manifest-types";
+
+export type { LockFile, ManifestBuildResult, ManifestScope };
+
+const manifestHeaderComment =
+  "# Generated by Skills Vault: https://github.com/xixu-me/skills-vault";
+
+function encodeDoubleQuotedYamlScalar(value: string): string {
+  return JSON.stringify(value);
+}
+
+/**
+ * Groups installed skills by source and renders the canonical manifest snapshot.
+ */
+export function buildManifest(
+  installedSkillNames: string[],
+  lockFile: LockFile,
+  scope: ManifestScope = "global",
+): ManifestBuildResult {
+  const lockSkills = lockFile.skills ?? {};
+  const missingSources: string[] = [];
+  const groups = new Map<string, string[]>();
+
+  for (const skillName of installedSkillNames) {
+    const source = lockSkills[skillName]?.source;
+    if (!source) {
+      missingSources.push(skillName);
+      continue;
+    }
+
+    const group = groups.get(source);
+    if (group) {
+      group.push(skillName);
+    } else {
+      groups.set(source, [skillName]);
+    }
+  }
+
+  if (missingSources.length > 0) {
+    throw new Error(
+      `Installed skill(s) missing tracked source in lock file: ${missingSources.join(", ")}`,
+    );
+  }
+
+  const sortedSources = Array.from(groups.keys()).sort((left, right) =>
+    left.localeCompare(right),
+  );
+  const lines: string[] = [manifestHeaderComment];
+
+  lines.push(`total_sources: ${sortedSources.length}`);
+  lines.push(`total_skills: ${installedSkillNames.length}`);
+  lines.push(`scope: ${encodeDoubleQuotedYamlScalar(scope)}`);
+  lines.push("");
+  lines.push("sources:");
+
+  for (const source of sortedSources) {
+    const skills = [...(groups.get(source) ?? [])].sort((left, right) =>
+      left.localeCompare(right),
+    );
+    lines.push(`  ${encodeDoubleQuotedYamlScalar(source)}:`);
+    lines.push(`    count: ${skills.length}`);
+    lines.push("    skills:");
+    for (const skill of skills) {
+      lines.push(`      - ${encodeDoubleQuotedYamlScalar(skill)}`);
+    }
+    lines.push("");
+  }
+
+  return {
+    yaml: `${lines.join("\n")}\n`,
+    totalSources: sortedSources.length,
+    totalSkills: installedSkillNames.length,
+  };
+}

package/src/internal/manifest/manifest-types.ts

@@ -0,0 +1,27 @@
+export type ManifestScope = "global" | "project";
+
+export type ManifestSourceEntry = {
+  count: number;
+  skills: string[];
+};
+
+export type Manifest = {
+  scope: ManifestScope;
+  totalSources: number;
+  totalSkills: number;
+  sources: Map<string, ManifestSourceEntry>;
+};
+
+export type LockSkillEntry = {
+  source?: string;
+};
+
+export type LockFile = {
+  skills?: Record<string, LockSkillEntry>;
+};
+
+export type ManifestBuildResult = {
+  yaml: string;
+  totalSources: number;
+  totalSkills: number;
+};

package/src/internal/manifest/parse-manifest.ts

@@ -0,0 +1,200 @@
+import { existsSync, readFileSync } from "node:fs";
+import { formatCliPath } from "../paths/format-cli-path";
+import type {
+  Manifest,
+  ManifestScope,
+  ManifestSourceEntry,
+} from "./manifest-types";
+
+export type { Manifest, ManifestScope, ManifestSourceEntry };
+
+function decodeYamlScalar(value: string): string {
+  return value.replaceAll("''", "'");
+}
+
+function decodeDoubleQuotedYamlScalar(value: string): string {
+  return JSON.parse(`"${value}"`) as string;
+}
+
+function parseQuotedSourceLine(line: string): string | null {
+  let match = line.match(/^  '((?:[^']|'')*)':$/);
+  if (match) {
+    return decodeYamlScalar(match[1]);
+  }
+
+  match = line.match(/^  "((?:[^"\\]|\\.)*)":$/);
+  if (match) {
+    return decodeDoubleQuotedYamlScalar(match[1]);
+  }
+
+  return null;
+}
+
+function parseQuotedSkillLine(line: string): string | null {
+  let match = line.match(/^      - '((?:[^']|'')*)'$/);
+  if (match) {
+    return decodeYamlScalar(match[1]);
+  }
+
+  match = line.match(/^      - "((?:[^"\\]|\\.)*)"$/);
+  if (match) {
+    return decodeDoubleQuotedYamlScalar(match[1]);
+  }
+
+  return null;
+}
+
+/**
+ * Parses manifest text into a validated in-memory model.
+ */
+export function parseManifestText(text: string, sourceLabel: string): Manifest {
+  const lines = text.split(/\r?\n/);
+  const sources = new Map<string, ManifestSourceEntry>();
+
+  let totalSources: number | null = null;
+  let totalSkills: number | null = null;
+  let scope: ManifestScope | null = null;
+  let currentSource: string | null = null;
+
+  lines.forEach((rawLine, index) => {
+    const line = rawLine.trimEnd();
+    const lineNumber = index + 1;
+    const trimmedLine = line.trim();
+
+    if (trimmedLine.length === 0 || trimmedLine.startsWith("#")) {
+      return;
+    }
+
+    let match = line.match(/^total_sources:\s+(\d+)$/);
+    if (match) {
+      totalSources = Number(match[1]);
+      return;
+    }
+
+    match = line.match(/^total_skills:\s+(\d+)$/);
+    if (match) {
+      totalSkills = Number(match[1]);
+      return;
+    }
+
+    match = line.match(/^scope:\s+'(global|project)'$/);
+    if (match) {
+      scope = match[1] as ManifestScope;
+      return;
+    }
+
+    match = line.match(/^scope:\s+"(global|project)"$/);
+    if (match) {
+      scope = match[1] as ManifestScope;
+      return;
+    }
+
+    if (line === "sources:") {
+      return;
+    }
+
+    const parsedSource = parseQuotedSourceLine(line);
+    if (parsedSource !== null) {
+      currentSource = parsedSource;
+      sources.set(currentSource, { count: Number.NaN, skills: [] });
+      return;
+    }
+
+    match = line.match(/^    count:\s+(\d+)$/);
+    if (match) {
+      if (!currentSource) {
+        throw new Error(
+          `Found count before source at ${sourceLabel}:${lineNumber}`,
+        );
+      }
+      const entry = sources.get(currentSource);
+      if (!entry) {
+        throw new Error(
+          `Internal parser error at ${sourceLabel}:${lineNumber}`,
+        );
+      }
+      entry.count = Number(match[1]);
+      return;
+    }
+
+    if (line === "    skills:") {
+      if (!currentSource) {
+        throw new Error(
+          `Found skills block before source at ${sourceLabel}:${lineNumber}`,
+        );
+      }
+      return;
+    }
+
+    const parsedSkill = parseQuotedSkillLine(line);
+    if (parsedSkill !== null) {
+      if (!currentSource) {
+        throw new Error(
+          `Found skill entry before source at ${sourceLabel}:${lineNumber}`,
+        );
+      }
+      const entry = sources.get(currentSource);
+      if (!entry) {
+        throw new Error(
+          `Internal parser error at ${sourceLabel}:${lineNumber}`,
+        );
+      }
+      entry.skills.push(parsedSkill);
+      return;
+    }
+
+    throw new Error(
+      `Unsupported manifest line at ${sourceLabel}:${lineNumber} -> ${line}`,
+    );
+  });
+
+  if (totalSources === null || totalSkills === null) {
+    throw new Error(
+      `Manifest is missing total_sources or total_skills: ${sourceLabel}`,
+    );
+  }
+
+  let actualSkillCount = 0;
+  for (const [source, entry] of sources) {
+    actualSkillCount += entry.skills.length;
+    if (!Number.isFinite(entry.count)) {
+      throw new Error(`Source '${source}' is missing count in ${sourceLabel}`);
+    }
+    if (entry.count !== entry.skills.length) {
+      throw new Error(
+        `Source '${source}' count mismatch in ${sourceLabel}: declared ${entry.count}, actual ${entry.skills.length}`,
+      );
+    }
+  }
+
+  if (totalSources !== sources.size) {
+    throw new Error(
+      `Manifest total_sources mismatch in ${sourceLabel}: declared ${totalSources}, actual ${sources.size}`,
+    );
+  }
+
+  if (totalSkills !== actualSkillCount) {
+    throw new Error(
+      `Manifest total_skills mismatch in ${sourceLabel}: declared ${totalSkills}, actual ${actualSkillCount}`,
+    );
+  }
+
+  return {
+    // Older manifests did not record scope, so global remains the safe default.
+    scope: scope ?? "global",
+    totalSources,
+    totalSkills,
+    sources,
+  };
+}
+
+/**
+ * Reads and parses a manifest file from disk.
+ */
+export function parseManifest(path: string): Manifest {
+  if (!existsSync(path)) {
+    throw new Error(`Manifest not found: ${formatCliPath(path)}`);
+  }
+
+  return parseManifestText(readFileSync(path, "utf8"), path);
+}

package/src/internal/paths/defaults.ts

@@ -0,0 +1,19 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const defaultManifestOptionPath = "./skvlt.yaml";
+
+/**
+ * Resolves the default manifest path against the caller's working directory.
+ */
+export function resolveDefaultManifestPath(baseDir: string = process.cwd()) {
+  return join(baseDir, "skvlt.yaml");
+}
+
+export const defaultGlobalLockFilePath = join(
+  homedir(),
+  ".agents",
+  ".skill-lock.json",
+);
+
+export const defaultGlobalSkillsPath = join(homedir(), ".agents", "skills");

package/src/internal/paths/format-cli-path.ts

@@ -0,0 +1,13 @@
+/**
+ * Normalizes filesystem paths for human-facing CLI output on the current host.
+ */
+export function formatCliPath(
+  filePath: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  if (platform !== "win32") {
+    return filePath;
+  }
+
+  return filePath.replaceAll("/", "\\");
+}

package/src/internal/process/list-installed-skill-names.ts

@@ -0,0 +1,27 @@
+import { runBunx, type BunxRunner } from "./run-bunx";
+
+/**
+ * Lists installed skill names for the selected scope via the upstream Skills CLI.
+ */
+export async function listInstalledSkillNames(
+  projectScope: boolean,
+  runBunxCommand: BunxRunner = runBunx,
+): Promise<string[]> {
+  const args = ["skills", "ls", "--json"];
+  if (!projectScope) {
+    args.splice(2, 0, "-g");
+  }
+
+  const result = await runBunxCommand(args);
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Unable to list installed skills for ${projectScope ? "project" : "global"} scope.\n${result.stderr || result.stdout}`,
+    );
+  }
+
+  const items = JSON.parse(result.stdout) as Array<{ name?: string }>;
+  return items
+    .map((item) => item.name)
+    .filter((name): name is string => typeof name === "string")
+    .sort((left, right) => left.localeCompare(right));
+}

package/src/internal/process/run-bunx.ts

@@ -0,0 +1,27 @@
+export type BunxResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+
+export type BunxRunner = (args: string[]) => Promise<BunxResult>;
+
+/**
+ * Runs `bunx` in the current workspace and captures its full text output.
+ */
+export async function runBunx(args: string[]): Promise<BunxResult> {
+  const proc = Bun.spawn({
+    cmd: ["bunx", ...args],
+    cwd: process.cwd(),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  return { stdout, stderr, exitCode };
+}