@baique/pi-web-sky 0.1.35 → 0.1.37

package/lib/skill-lock.test.mjs

@@ -0,0 +1,182 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url);
+const { annotateSkillsWithInstallInfo, getGlobalSkillsLockPath } =
+  await jiti.import("./skill-lock.ts");
+
+function writeJson(path, value) {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function makeSkill(name, filePath, scope) {
+  return {
+    name,
+    description: `${name} description`,
+    filePath,
+    baseDir: filePath.slice(0, -"/SKILL.md".length),
+    disableModelInvocation: false,
+    sourceInfo: { scope },
+  };
+}
+
+test("uses the CLI global lock location", () => {
+  assert.equal(
+    getGlobalSkillsLockPath({ homeDir: "/home/test", xdgStateHome: undefined }),
+    join("/home/test", ".agents", ".skill-lock.json"),
+  );
+  assert.equal(
+    getGlobalSkillsLockPath({ homeDir: "/home/test", xdgStateHome: "/state" }),
+    join("/state", "skills", ".skill-lock.json"),
+  );
+});
+
+test("annotates only lock entries that exist in the matching Pi scope", () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-web-skill-lock-"));
+  try {
+    const cwd = join(root, "project");
+    const agentDir = join(root, "home", ".pi", "agent");
+    const globalLockPath = join(root, "global-lock.json");
+    const projectLockPath = join(cwd, "skills-lock.json");
+    const globalSkillPath = join(agentDir, "skills", "edge-tts", "SKILL.md");
+    const projectSkillPath = join(cwd, ".pi", "skills", "find-skills", "SKILL.md");
+    const manualSkillPath = join(agentDir, "skills", "manual", "SKILL.md");
+    const otherAgentSkillPath = join(root, "other-agent", "tts", "SKILL.md");
+
+    for (const path of [globalSkillPath, projectSkillPath, manualSkillPath, otherAgentSkillPath]) {
+      mkdirSync(join(path, ".."), { recursive: true });
+      writeFileSync(path, "---\nname: test\n---\n", "utf8");
+    }
+
+    writeJson(globalLockPath, {
+      version: 3,
+      skills: {
+        "edge-tts": {
+          source: "https://github.com/aahl/skills.git",
+          sourceType: "github",
+          skillPath: "skills/edge-tts/SKILL.md",
+          skillFolderHash: "global-version",
+        },
+        tts: { source: "noizai/skills", sourceType: "github" },
+      },
+    });
+    writeJson(projectLockPath, {
+      version: 1,
+      skills: {
+        "find-skills": {
+          source: "vercel-labs/skills",
+          sourceType: "github",
+          skillPath: "skills/find-skills/SKILL.md",
+          computedHash: "project-version",
+        },
+      },
+    });
+
+    const annotated = annotateSkillsWithInstallInfo(
+      [
+        makeSkill("edge-tts", globalSkillPath, "user"),
+        makeSkill("find-skills", projectSkillPath, "project"),
+        makeSkill("manual", manualSkillPath, "user"),
+        makeSkill("tts", otherAgentSkillPath, "user"),
+      ],
+      { cwd, agentDir, globalLockPath, projectLockPath },
+    );
+
+    assert.deepEqual(annotated[0].install, {
+      package: "aahl/skills@edge-tts",
+      scope: "global",
+      source: "aahl/skills",
+      sourceType: "github",
+      skillsShUrl: "https://skills.sh/aahl/skills/edge-tts",
+      skillPath: "skills/edge-tts/SKILL.md",
+      versionHash: "global-version",
+      canCheckForUpdates: true,
+    });
+    assert.deepEqual(annotated[1].install, {
+      package: "vercel-labs/skills@find-skills",
+      scope: "project",
+      source: "vercel-labs/skills",
+      sourceType: "github",
+      skillsShUrl: "https://skills.sh/vercel-labs/skills/find-skills",
+      skillPath: "skills/find-skills/SKILL.md",
+      versionHash: "project-version",
+      canCheckForUpdates: true,
+    });
+    assert.equal(annotated[2].install, undefined);
+    assert.equal(annotated[3].install, undefined);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("ignores stale lock entries and malformed lock files", () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-web-skill-lock-"));
+  try {
+    const cwd = join(root, "project");
+    const agentDir = join(root, "agent");
+    const missingPath = join(agentDir, "skills", "missing", "SKILL.md");
+    const projectSkillPath = join(cwd, ".pi", "skills", "broken", "SKILL.md");
+    const globalLockPath = join(root, "global-lock.json");
+    const projectLockPath = join(root, "project-lock.json");
+    mkdirSync(join(projectSkillPath, ".."), { recursive: true });
+    writeFileSync(projectSkillPath, "---\nname: broken\n---\n", "utf8");
+    writeJson(globalLockPath, {
+      version: 3,
+      skills: {
+        missing: { source: "owner/repo", sourceType: "github" },
+      },
+    });
+    writeFileSync(projectLockPath, "not json", "utf8");
+
+    const skills = annotateSkillsWithInstallInfo(
+      [
+        makeSkill("missing", missingPath, "user"),
+        makeSkill("broken", projectSkillPath, "project"),
+      ],
+      { cwd, agentDir, globalLockPath, projectLockPath },
+    );
+
+    assert.equal(skills[0].install, undefined);
+    assert.equal(skills[1].install, undefined);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("does not compare a project ref with the default skills.sh snapshot", () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-web-skill-lock-"));
+  try {
+    const cwd = join(root, "project");
+    const agentDir = join(root, "agent");
+    const projectLockPath = join(cwd, "skills-lock.json");
+    const projectSkillPath = join(cwd, ".pi", "skills", "preview", "SKILL.md");
+    mkdirSync(join(projectSkillPath, ".."), { recursive: true });
+    writeFileSync(projectSkillPath, "---\nname: preview\n---\n", "utf8");
+    writeJson(projectLockPath, {
+      version: 1,
+      skills: {
+        preview: {
+          source: "owner/repo",
+          sourceType: "github",
+          skillPath: "skills/preview/SKILL.md",
+          ref: "preview",
+          computedHash: "project-version",
+        },
+      },
+    });
+
+    const [skill] = annotateSkillsWithInstallInfo(
+      [makeSkill("preview", projectSkillPath, "project")],
+      { cwd, agentDir, projectLockPath, globalLockPath: join(root, "missing.json") },
+    );
+
+    assert.equal(skill.install.ref, "preview");
+    assert.equal(skill.install.canCheckForUpdates, false);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/lib/skill-lock.ts

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { isAbsolute, join, relative, resolve, sep } from "path";
+import type { SkillInfo, SkillInstallInfo, SkillInstallScope } from "@/lib/api-types";
+
+interface SkillLockEntry {
+  source?: unknown;
+  sourceType?: unknown;
+  skillPath?: unknown;
+  ref?: unknown;
+  skillFolderHash?: unknown;
+  computedHash?: unknown;
+}
+
+interface SkillLockFile {
+  skills?: Record<string, SkillLockEntry>;
+}
+
+interface GlobalLockPathOptions {
+  homeDir?: string;
+  xdgStateHome?: string;
+}
+
+interface AnnotateSkillOptions {
+  cwd: string;
+  agentDir: string;
+  globalLockPath?: string;
+  projectLockPath?: string;
+}
+
+export function getGlobalSkillsLockPath({
+  homeDir = homedir(),
+  xdgStateHome = process.env.XDG_STATE_HOME,
+}: GlobalLockPathOptions = {}): string {
+  return xdgStateHome
+    ? join(xdgStateHome, "skills", ".skill-lock.json")
+    : join(homeDir, ".agents", ".skill-lock.json");
+}
+
+function readSkillLock(path: string): Record<string, SkillLockEntry> {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as SkillLockFile;
+    return parsed.skills && typeof parsed.skills === "object" ? parsed.skills : {};
+  } catch {
+    return {};
+  }
+}
+
+function isWithin(path: string, root: string): boolean {
+  const rel = relative(resolve(root), resolve(path));
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+function findLockEntry(
+  entries: Record<string, SkillLockEntry>,
+  skillName: string,
+): SkillLockEntry | undefined {
+  if (entries[skillName]) return entries[skillName];
+  const normalizedName = skillName.toLowerCase();
+  const key = Object.keys(entries).find((name) => name.toLowerCase() === normalizedName);
+  return key ? entries[key] : undefined;
+}
+
+function normalizeSource(source: string, sourceType?: string): string {
+  if (sourceType !== "github") return source.replace(/\/$/, "");
+  return source
+    .replace(/^git\+/, "")
+    .replace(/^https?:\/\/github\.com\//, "")
+    .replace(/^git@github\.com:/, "")
+    .replace(/\.git$/, "")
+    .replace(/\/$/, "");
+}
+
+function buildSkillsShUrl(source: string, skillName: string): string | undefined {
+  if (!source || source.includes("://") || source.startsWith("git@")) return undefined;
+  const sourcePath = source
+    .split("/")
+    .filter(Boolean)
+    .map(encodeURIComponent)
+    .join("/");
+  if (!sourcePath) return undefined;
+  return `https://skills.sh/${sourcePath}/${encodeURIComponent(skillName)}`;
+}
+
+function getInstallInfo(
+  entries: Record<string, SkillLockEntry>,
+  skillName: string,
+  scope: SkillInstallScope,
+): SkillInstallInfo | undefined {
+  const entry = findLockEntry(entries, skillName);
+  if (!entry || typeof entry.source !== "string" || !entry.source.trim()) return undefined;
+
+  const sourceType = typeof entry.sourceType === "string" ? entry.sourceType : undefined;
+  const source = normalizeSource(entry.source.trim(), sourceType);
+  if (!source) return undefined;
+  const skillPath = typeof entry.skillPath === "string" ? entry.skillPath : undefined;
+  const ref = typeof entry.ref === "string" ? entry.ref : undefined;
+  const rawVersionHash = scope === "global" ? entry.skillFolderHash : entry.computedHash;
+  const versionHash = typeof rawVersionHash === "string" && rawVersionHash
+    ? rawVersionHash
+    : undefined;
+  const isGitHubSource =
+    sourceType === "github" && /^[\w.-]+\/[\w.-]+$/.test(source);
+  const hasComparableVersion = scope === "global" || !ref;
+
+  return {
+    package: `${source}@${skillName}`,
+    scope,
+    source,
+    sourceType,
+    skillsShUrl: sourceType === "local" ? undefined : buildSkillsShUrl(source, skillName),
+    ...(skillPath && { skillPath }),
+    ...(ref && { ref }),
+    ...(versionHash && { versionHash }),
+    canCheckForUpdates: Boolean(
+      isGitHubSource && skillPath && versionHash && hasComparableVersion,
+    ),
+  };
+}
+
+export function annotateSkillsWithInstallInfo(
+  skills: SkillInfo[],
+  {
+    cwd,
+    agentDir,
+    globalLockPath = getGlobalSkillsLockPath(),
+    projectLockPath = join(cwd, "skills-lock.json"),
+  }: AnnotateSkillOptions,
+): SkillInfo[] {
+  const globalEntries = readSkillLock(globalLockPath);
+  const projectEntries = readSkillLock(projectLockPath);
+  const globalSkillsRoot = join(agentDir, "skills");
+  const projectSkillsRoot = join(cwd, ".pi", "skills");
+
+  return skills.map((skill) => {
+    if (!existsSync(skill.filePath)) return skill;
+
+    const install = isWithin(skill.filePath, globalSkillsRoot)
+      ? getInstallInfo(globalEntries, skill.name, "global")
+      : isWithin(skill.filePath, projectSkillsRoot)
+        ? getInstallInfo(projectEntries, skill.name, "project")
+        : undefined;
+
+    return install ? { ...skill, install } : skill;
+  });
+}

package/lib/skill-updates.test.mjs

@@ -0,0 +1,182 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url);
+const {
+  buildSkillUpdateArgs,
+  checkSkillUpdate,
+  checkSkillUpdates,
+  skillUpdateKey,
+} = await jiti.import("./skill-updates.ts");
+
+function install(overrides = {}) {
+  return {
+    package: "owner/repo@example-skill",
+    scope: "global",
+    source: "owner/repo",
+    sourceType: "github",
+    skillsShUrl: "https://skills.sh/owner/repo/example-skill",
+    skillPath: "skills/example-skill/SKILL.md",
+    versionHash: "current-hash",
+    canCheckForUpdates: true,
+    ...overrides,
+  };
+}
+
+function jsonResponse(value, status = 200) {
+  return new Response(JSON.stringify(value), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+test("compares a global lock version with the remote Git tree", async () => {
+  const seen = [];
+  const upToDate = await checkSkillUpdate(install(), {
+    fetcher: async (url) => {
+      seen.push(url);
+      return jsonResponse({
+        sha: "root-hash",
+        tree: [{ type: "tree", path: "skills/example-skill", sha: "current-hash" }],
+      });
+    },
+  });
+
+  assert.equal(upToDate.state, "up-to-date");
+  assert.equal(upToDate.latestVersion, "current-hash");
+  assert.match(seen[0], /repos\/owner\/repo\/git\/trees\/HEAD/);
+
+  const available = await checkSkillUpdate(install(), {
+    fetcher: async () => jsonResponse({
+      sha: "root-hash",
+      tree: [{ type: "tree", path: "skills/example-skill", sha: "next-hash" }],
+    }),
+  });
+  assert.equal(available.state, "update-available");
+  assert.equal(available.currentVersion, "current-hash");
+  assert.equal(available.latestVersion, "next-hash");
+});
+
+test("uses the repository hash for a root global skill", async () => {
+  const result = await checkSkillUpdate(install({ skillPath: "SKILL.md" }), {
+    fetcher: async () => jsonResponse({ sha: "next-root", tree: [] }),
+  });
+
+  assert.equal(result.state, "update-available");
+  assert.equal(result.latestVersion, "next-root");
+});
+
+test("compares a project lock version with the skills.sh snapshot", async () => {
+  let requestedUrl = "";
+  const result = await checkSkillUpdate(install({ scope: "project" }), {
+    skillsApiBase: "https://skills.test",
+    fetcher: async (url) => {
+      requestedUrl = url;
+      return jsonResponse({ hash: "current-hash" });
+    },
+  });
+
+  assert.equal(result.state, "up-to-date");
+  assert.equal(
+    requestedUrl,
+    "https://skills.test/api/download/owner/repo/example-skill",
+  );
+});
+
+test("returns unsupported without making a remote request", async () => {
+  let called = false;
+  const result = await checkSkillUpdate(
+    install({ canCheckForUpdates: false, versionHash: undefined }),
+    { fetcher: async () => { called = true; return jsonResponse({}); } },
+  );
+
+  assert.equal(result.state, "unsupported");
+  assert.equal(called, false);
+});
+
+test("returns a scoped error when the remote check fails", async () => {
+  const result = await checkSkillUpdate(install(), {
+    fetcher: async () => jsonResponse({}, 503),
+  });
+
+  assert.equal(result.state, "error");
+  assert.equal(result.message, "HTTP 503");
+  assert.equal(skillUpdateKey(install()), "global\0owner/repo@example-skill");
+});
+
+test("falls back to Git when the GitHub API is rate limited", async () => {
+  let resolved = false;
+  const result = await checkSkillUpdate(install(), {
+    fetcher: async () => jsonResponse({}, 403),
+    resolveGitTreeHash: async () => {
+      resolved = true;
+      return "next-hash";
+    },
+  });
+
+  assert.equal(resolved, true);
+  assert.equal(result.state, "update-available");
+  assert.equal(result.latestVersion, "next-hash");
+});
+
+test("builds Pi-only update commands for each scope", () => {
+  assert.deepEqual(buildSkillUpdateArgs(install()), [
+    "skills",
+    "add",
+    "owner/repo/skills/example-skill",
+    "--skill",
+    "example-skill",
+    "-y",
+    "--agent",
+    "pi",
+    "-g",
+  ]);
+  assert.deepEqual(buildSkillUpdateArgs(install({ scope: "project" })), [
+    "skills",
+    "add",
+    "owner/repo/skills/example-skill",
+    "--skill",
+    "example-skill",
+    "-y",
+    "--agent",
+    "pi",
+  ]);
+  assert.deepEqual(buildSkillUpdateArgs(install({ ref: "release/v2" })), [
+    "skills",
+    "add",
+    "owner/repo/skills/example-skill#release%2Fv2",
+    "--skill",
+    "example-skill",
+    "-y",
+    "--agent",
+    "pi",
+    "-g",
+  ]);
+});
+
+test("reuses one remote request for skills from the same GitHub source", async () => {
+  let requests = 0;
+  const results = await checkSkillUpdates([
+    install(),
+    install({
+      package: "owner/repo@another-skill",
+      skillPath: "skills/another-skill/SKILL.md",
+      versionHash: "another-hash",
+    }),
+  ], {
+    fetcher: async () => {
+      requests++;
+      return jsonResponse({
+        sha: "root-hash",
+        tree: [
+          { type: "tree", path: "skills/example-skill", sha: "current-hash" },
+          { type: "tree", path: "skills/another-skill", sha: "another-hash" },
+        ],
+      });
+    },
+  });
+
+  assert.equal(requests, 1);
+  assert.deepEqual(results.map((item) => item.state), ["up-to-date", "up-to-date"]);
+});