Skip to content

Commit d79d831

Browse files
committed
feat: add deterministic lockfile generation
1 parent 9ed82d9 commit d79d831

2 files changed

Lines changed: 344 additions & 0 deletions

File tree

‎src/lockfile/generate-lock.ts‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
import fs from "node:fs";
2+
import path from "node:path";
3+
import { stringify as toYaml } from "yaml";
4+
import { parseSkillMarkdown } from "../skills/skill";
5+
6+
export const SOURCE_METADATA_FILENAME = ".skillet-source.json";
7+
8+
export type GenerateLockfileOptions = {
9+
scope: "project" | "global";
10+
cwd?: string;
11+
homeDir?: string;
12+
};
13+
14+
export type LockfileSource = {
15+
type: string;
16+
url: string;
17+
ref?: string;
18+
digest?: string;
19+
installMethod: string;
20+
skills: string[];
21+
agents: string[];
22+
};
23+
24+
export type LockfileDocument = {
25+
version: 1;
26+
sources: LockfileSource[];
27+
};
28+
29+
export type GenerateLockfileResult = {
30+
outputPath: string;
31+
yaml: string;
32+
lockfile: LockfileDocument;
33+
};
34+
35+
const AGENT_SKILL_DIRS = [
36+
{ agent: "claude", relativePath: ".claude/skills" },
37+
{ agent: "codex", relativePath: ".codex/skills" },
38+
{ agent: "opencode", relativePath: ".opencode/skills" },
39+
{ agent: "cursor", relativePath: ".cursor/skills" },
40+
{ agent: "windsurf", relativePath: ".windsurf/skills" },
41+
] as const;
42+
43+
export function generateLockfile(options: GenerateLockfileOptions): GenerateLockfileResult {
44+
const cwd = path.resolve(options.cwd ?? process.cwd());
45+
const homeDir = path.resolve(options.homeDir ?? cwd);
46+
47+
const scanRoot = options.scope === "project" ? cwd : homeDir;
48+
const outputPath =
49+
options.scope === "project"
50+
? path.join(cwd, "skillet.lock.yaml")
51+
: path.join(homeDir, ".skillet", "skillet.lock.yaml");
52+
53+
const groupedSources = new Map<
54+
string,
55+
{
56+
source: Omit<LockfileSource, "skills" | "agents">;
57+
skills: Set<string>;
58+
agents: Set<string>;
59+
}
60+
>();
61+
62+
for (const config of AGENT_SKILL_DIRS) {
63+
const agentSkillsDir = path.join(scanRoot, config.relativePath);
64+
if (!isDirectory(agentSkillsDir)) {
65+
continue;
66+
}
67+
68+
for (const skillDir of listSkillDirectories(agentSkillsDir)) {
69+
const skillFile = path.join(skillDir, "SKILL.md");
70+
if (!isFile(skillFile)) {
71+
continue;
72+
}
73+
74+
let skillName: string;
75+
try {
76+
skillName = parseSkillMarkdown(fs.readFileSync(skillFile, "utf8"), { path: skillFile }).frontmatter.name;
77+
} catch {
78+
continue;
79+
}
80+
81+
const metadata = readSourceMetadata(skillDir);
82+
const installMethod =
83+
metadata.installMethod ?? (fs.lstatSync(skillDir).isSymbolicLink() ? "symlink" : "copy");
84+
const source = {
85+
type: metadata.type ?? "unknown",
86+
url: metadata.url ?? `file://${skillDir}`,
87+
ref: metadata.ref,
88+
digest: metadata.digest,
89+
installMethod,
90+
};
91+
92+
const key = [source.type, source.url, source.ref ?? "", source.digest ?? "", source.installMethod].join("|");
93+
const grouped = groupedSources.get(key) ?? {
94+
source,
95+
skills: new Set<string>(),
96+
agents: new Set<string>(),
97+
};
98+
99+
grouped.skills.add(skillName);
100+
grouped.agents.add(config.agent);
101+
groupedSources.set(key, grouped);
102+
}
103+
}
104+
105+
const sources: LockfileSource[] = [...groupedSources.values()]
106+
.map(({ source, skills, agents }) => {
107+
const normalized: LockfileSource = {
108+
type: source.type,
109+
url: source.url,
110+
installMethod: source.installMethod,
111+
skills: [...skills].sort((a, b) => a.localeCompare(b)),
112+
agents: [...agents].sort((a, b) => a.localeCompare(b)),
113+
};
114+
115+
if (source.ref) {
116+
normalized.ref = source.ref;
117+
}
118+
if (source.digest) {
119+
normalized.digest = source.digest;
120+
}
121+
122+
return normalized;
123+
})
124+
.sort((left, right) => {
125+
const sortKeys: Array<keyof LockfileSource> = ["type", "url", "ref", "digest", "installMethod"];
126+
for (const key of sortKeys) {
127+
const leftValue = left[key] ?? "";
128+
const rightValue = right[key] ?? "";
129+
const compare = String(leftValue).localeCompare(String(rightValue));
130+
if (compare !== 0) {
131+
return compare;
132+
}
133+
}
134+
return 0;
135+
});
136+
137+
const lockfile: LockfileDocument = {
138+
version: 1,
139+
sources,
140+
};
141+
142+
const yaml = toYaml(lockfile);
143+
fs.mkdirSync(path.dirname(outputPath), { recursive: true });
144+
fs.writeFileSync(outputPath, yaml);
145+
146+
return {
147+
outputPath,
148+
yaml,
149+
lockfile,
150+
};
151+
}
152+
153+
type SourceMetadata = {
154+
type?: string;
155+
url?: string;
156+
ref?: string;
157+
digest?: string;
158+
installMethod?: string;
159+
};
160+
161+
function readSourceMetadata(skillDir: string): SourceMetadata {
162+
const metadataPath = path.join(skillDir, SOURCE_METADATA_FILENAME);
163+
if (!isFile(metadataPath)) {
164+
return {};
165+
}
166+
167+
try {
168+
const parsed = JSON.parse(fs.readFileSync(metadataPath, "utf8")) as Record<string, unknown>;
169+
return {
170+
type: readOptionalString(parsed.type),
171+
url: readOptionalString(parsed.url),
172+
ref: readOptionalString(parsed.ref),
173+
digest: readOptionalString(parsed.digest),
174+
installMethod: readOptionalString(parsed.installMethod),
175+
};
176+
} catch {
177+
return {};
178+
}
179+
}
180+
181+
function readOptionalString(value: unknown): string | undefined {
182+
if (typeof value !== "string" || value.trim().length === 0) {
183+
return undefined;
184+
}
185+
186+
return value;
187+
}
188+
189+
function listSkillDirectories(agentSkillsDir: string): string[] {
190+
const directories: string[] = [];
191+
for (const entry of fs.readdirSync(agentSkillsDir, { withFileTypes: true })) {
192+
const candidate = path.join(agentSkillsDir, entry.name);
193+
if (entry.isDirectory() || (entry.isSymbolicLink() && isDirectory(candidate))) {
194+
directories.push(candidate);
195+
}
196+
}
197+
198+
return directories.sort((a, b) => a.localeCompare(b));
199+
}
200+
201+
function isDirectory(candidatePath: string): boolean {
202+
try {
203+
return fs.statSync(candidatePath).isDirectory();
204+
} catch {
205+
return false;
206+
}
207+
}
208+
209+
function isFile(candidatePath: string): boolean {
210+
try {
211+
return fs.statSync(candidatePath).isFile();
212+
} catch {
213+
return false;
214+
}
215+
}
Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
import fs from "node:fs";
2+
import os from "node:os";
3+
import path from "node:path";
4+
import { afterEach, describe, expect, test } from "vitest";
5+
import { parse as parseYaml } from "yaml";
6+
import { generateLockfile } from "../../src/lockfile/generate-lock";
7+
8+
const tempDirs: string[] = [];
9+
10+
function makeTempDir(prefix: string): string {
11+
const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
12+
tempDirs.push(dir);
13+
return dir;
14+
}
15+
16+
function createInstalledSkill(
17+
rootDir: string,
18+
agentDir: string,
19+
skillName: string,
20+
metadata: Record<string, string>
21+
): void {
22+
const skillDir = path.join(rootDir, agentDir, skillName);
23+
fs.mkdirSync(skillDir, { recursive: true });
24+
fs.writeFileSync(
25+
path.join(skillDir, "SKILL.md"),
26+
`---\nname: ${skillName}\ndescription: ${skillName}\n---\n\n# ${skillName}\n`
27+
);
28+
fs.writeFileSync(path.join(skillDir, ".skillet-source.json"), JSON.stringify(metadata, null, 2));
29+
}
30+
31+
afterEach(() => {
32+
for (const dir of tempDirs.splice(0)) {
33+
fs.rmSync(dir, { recursive: true, force: true });
34+
}
35+
});
36+
37+
describe("generateLockfile", () => {
38+
test("generates deterministic project-scope lockfile", () => {
39+
const cwd = makeTempDir("skillet-lock-project-");
40+
const homeDir = path.join(cwd, "home");
41+
42+
createInstalledSkill(cwd, ".codex/skills", "alpha", {
43+
type: "git",
44+
url: "https://github.com/echohello-dev/skills.git",
45+
ref: "main",
46+
installMethod: "symlink",
47+
});
48+
49+
createInstalledSkill(cwd, ".claude/skills", "beta", {
50+
type: "oci",
51+
url: "oci://ghcr.io/echohello/skills",
52+
digest: "sha256:abc123",
53+
installMethod: "copy",
54+
});
55+
56+
const first = generateLockfile({ scope: "project", cwd, homeDir });
57+
const second = generateLockfile({ scope: "project", cwd, homeDir });
58+
59+
expect(first.outputPath).toBe(path.join(cwd, "skillet.lock.yaml"));
60+
expect(first.yaml).toBe(second.yaml);
61+
62+
const parsed = parseYaml(first.yaml) as {
63+
version: number;
64+
sources: Array<{ type: string; skills: string[]; agents: string[] }>;
65+
};
66+
67+
expect(parsed.version).toBe(1);
68+
expect(parsed.sources).toHaveLength(2);
69+
expect(parsed.sources[0]?.type).toBe("git");
70+
expect(parsed.sources[0]?.skills).toEqual(["alpha"]);
71+
expect(parsed.sources[0]?.agents).toEqual(["codex"]);
72+
expect(parsed.sources[1]?.type).toBe("oci");
73+
expect(parsed.sources[1]?.skills).toEqual(["beta"]);
74+
expect(parsed.sources[1]?.agents).toEqual(["claude"]);
75+
});
76+
77+
test("generates global-scope lockfile in home directory", () => {
78+
const cwd = makeTempDir("skillet-lock-global-cwd-");
79+
const homeDir = makeTempDir("skillet-lock-global-home-");
80+
81+
createInstalledSkill(homeDir, ".codex/skills", "gamma", {
82+
type: "http",
83+
url: "https://example.com/archive.tar.gz",
84+
ref: "v1.0.0",
85+
installMethod: "copy",
86+
});
87+
88+
const result = generateLockfile({ scope: "global", cwd, homeDir });
89+
90+
expect(result.outputPath).toBe(path.join(homeDir, ".skillet", "skillet.lock.yaml"));
91+
expect(fs.existsSync(result.outputPath)).toBe(true);
92+
93+
const parsed = parseYaml(result.yaml) as {
94+
sources: Array<{ type: string; skills: string[]; agents: string[] }>;
95+
};
96+
97+
expect(parsed.sources).toHaveLength(1);
98+
expect(parsed.sources[0]?.type).toBe("http");
99+
expect(parsed.sources[0]?.skills).toEqual(["gamma"]);
100+
expect(parsed.sources[0]?.agents).toEqual(["codex"]);
101+
});
102+
103+
test("groups multiple skills from the same source with stable ordering", () => {
104+
const cwd = makeTempDir("skillet-lock-group-");
105+
const homeDir = path.join(cwd, "home");
106+
107+
createInstalledSkill(cwd, ".codex/skills", "zeta", {
108+
type: "git",
109+
url: "https://github.com/echohello-dev/skills.git",
110+
ref: "main",
111+
installMethod: "symlink",
112+
});
113+
createInstalledSkill(cwd, ".codex/skills", "alpha", {
114+
type: "git",
115+
url: "https://github.com/echohello-dev/skills.git",
116+
ref: "main",
117+
installMethod: "symlink",
118+
});
119+
120+
const result = generateLockfile({ scope: "project", cwd, homeDir });
121+
const parsed = parseYaml(result.yaml) as {
122+
sources: Array<{ skills: string[]; agents: string[] }>;
123+
};
124+
125+
expect(parsed.sources).toHaveLength(1);
126+
expect(parsed.sources[0]?.skills).toEqual(["alpha", "zeta"]);
127+
expect(parsed.sources[0]?.agents).toEqual(["codex"]);
128+
});
129+
});

0 commit comments

Comments
 (0)