@tanstack/ai-skills 0.0.0 → 0.1.0

package/dist/esm/node/index.js

@@ -0,0 +1,198 @@
+import { parseSkill, stripFrontmatter } from "../parse.js";
+import { walkSkillDirs } from "../walk.js";
+import { assertSafeResourcePath, stableHash } from "../util.js";
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import { basename, join, relative, sep } from "node:path";
+//#region src/node/index.ts
+/**
+* `skillDirectory` — a filesystem-backed {@link SkillSource}. Lives behind the
+* `/node` subpath because it imports `node:fs`; the root export stays edge-safe
+* (Workers, browsers), mirroring `@tanstack/ai-code-mode-snippets/storage`.
+*/
+var RESOURCE_DIRS = ["references", "assets"];
+var SCRIPT_DIR = "scripts";
+var nodeLister = async (dir) => {
+	return (await readdir(dir, { withFileTypes: true })).map((e) => ({
+		name: e.name,
+		path: join(dir, e.name),
+		type: e.isDirectory() ? "dir" : "file"
+	}));
+};
+/** Recursively collect file paths under `dir`, relative to `root`. */
+async function collectFiles(dir, root) {
+	let ents;
+	try {
+		ents = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const out = [];
+	for (const e of ents) {
+		const full = join(dir, e.name);
+		if (e.isDirectory()) out.push(...await collectFiles(full, root));
+		else out.push(relative(root, full).replace(/\\/g, "/"));
+	}
+	return out;
+}
+function posixRel(path) {
+	return path.replace(/\\/g, "/");
+}
+function hasPrefix(rel, prefixes) {
+	const n = posixRel(rel);
+	return prefixes.some((p) => n === p || n.startsWith(`${p}/`));
+}
+async function resolveInside(dir, rel) {
+	const full = join(dir, rel);
+	const rootReal = await realpath(dir);
+	const fullReal = await realpath(full);
+	const prefix = rootReal.endsWith(sep) ? rootReal : rootReal + sep;
+	if (fullReal !== rootReal && !fullReal.startsWith(prefix)) throw new Error(`unsafe resource path: "${rel}"`);
+	return fullReal;
+}
+function skillDirectory(root, options = {}) {
+	const roots = Array.isArray(root) ? root : [root];
+	const { maxDepth, strict = true } = options;
+	/** Fresh scan of every root → parsed skill name → skill directory. First wins. */
+	const scan = async () => {
+		const map = /* @__PURE__ */ new Map();
+		for (const r of roots) {
+			const dirs = await walkSkillDirs(nodeLister, r, { maxDepth });
+			for (const d of dirs) {
+				const raw = await readFile(join(d.dir, "SKILL.md"), "utf8").catch(() => void 0);
+				if (raw === void 0) continue;
+				try {
+					const parsed = parseSkill(raw, {
+						dirName: basename(d.dir),
+						strict
+					});
+					if (!map.has(parsed.metadata.name)) map.set(parsed.metadata.name, d.dir);
+				} catch {}
+			}
+		}
+		return map;
+	};
+	const dirOf = async (name) => {
+		const dir = (await scan()).get(name);
+		if (!dir) throw new Error(`no skill named "${name}" under ${roots.join(", ")}`);
+		return dir;
+	};
+	return {
+		revision: async () => {
+			const map = await scan();
+			const parts = [];
+			for (const [name, dir] of [...map].sort()) {
+				const s = await stat(join(dir, "SKILL.md")).catch(() => void 0);
+				parts.push(`${name}:${s?.mtimeMs ?? 0}:${s?.size ?? 0}`);
+			}
+			return stableHash(parts.join("|"));
+		},
+		list: async () => {
+			const map = await scan();
+			const out = [];
+			for (const [, dir] of map) {
+				const raw = await readFile(join(dir, "SKILL.md"), "utf8").catch(() => void 0);
+				if (raw === void 0) continue;
+				try {
+					out.push(parseSkill(raw, {
+						dirName: basename(dir),
+						strict
+					}).metadata);
+				} catch {}
+			}
+			return out;
+		},
+		load: async (name) => readFile(join(await dirOf(name), "SKILL.md"), "utf8"),
+		listResources: async (name) => {
+			const dir = await dirOf(name);
+			const files = [];
+			for (const sub of RESOURCE_DIRS) files.push(...await collectFiles(join(dir, sub), dir));
+			return files;
+		},
+		readResource: async (name, path) => {
+			assertSafeResourcePath(path);
+			if (!hasPrefix(path, RESOURCE_DIRS)) throw new Error(`resource path must be under references/ or assets/: "${path}"`);
+			const fullReal = await resolveInside(await dirOf(name), path);
+			if (hasPrefix(path, ["references"])) return readFile(fullReal, "utf8");
+			return readFile(fullReal);
+		},
+		listScripts: async (name) => {
+			const dir = await dirOf(name);
+			return (await collectFiles(join(dir, SCRIPT_DIR), dir)).map((p) => ({
+				path: p,
+				executable: false,
+				reason: "no-runtime"
+			}));
+		},
+		readScript: async (name, path) => {
+			assertSafeResourcePath(path);
+			if (!hasPrefix(path, [SCRIPT_DIR])) throw new Error(`script path must be under scripts/: "${path}"`);
+			const fullReal = await resolveInside(await dirOf(name), path);
+			const bytes = await readFile(fullReal);
+			return new Uint8Array(bytes);
+		}
+	};
+}
+/**
+* Read a skill directory tree into a plain {@link GeneratedCatalog} — the shape
+* `staticSkills` consumes. Used by the Vite plugin and directly available for
+* custom build scripts.
+*/
+async function generateCatalog(root, options = {}) {
+	const roots = Array.isArray(root) ? root : [root];
+	const skills = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const r of roots) for (const { dir } of await walkSkillDirs(nodeLister, r, { maxDepth: options.maxDepth })) {
+		const raw = await readFile(join(dir, "SKILL.md"), "utf8").catch(() => void 0);
+		if (raw === void 0) continue;
+		let meta;
+		try {
+			meta = parseSkill(raw, {
+				dirName: basename(dir),
+				strict: options.strict ?? true
+			}).metadata;
+		} catch {
+			continue;
+		}
+		if (seen.has(meta.name)) continue;
+		seen.add(meta.name);
+		const resources = {};
+		for (const sub of RESOURCE_DIRS) for (const rel of await collectFiles(join(dir, sub), dir)) resources[rel] = await readFile(join(dir, rel), "utf8").catch(() => "");
+		skills.push({
+			name: meta.name,
+			description: meta.description,
+			body: stripFrontmatter(raw),
+			...meta.compatibility && { compatibility: meta.compatibility },
+			...Object.keys(resources).length && { resources }
+		});
+	}
+	skills.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+	return {
+		revision: stableHash(skills.map((s) => `${s.name}:${stableHash(s.body)}`).join("|")),
+		skills
+	};
+}
+/**
+* Vite plugin that globs `SKILL.md` under `dir` at build time and serves a
+* virtual module (default id `virtual:tanstack-skills`) exporting the catalog
+* `as const`. Consumers then wrap it with `staticSkills` for a literal-union of
+* skill names. The catalog is embedded as JSON, so the bundle hash tracks it.
+*/
+function skillsCatalogPlugin(options = {}) {
+	const virtualId = options.virtualId ?? "virtual:tanstack-skills";
+	const resolved = `\0${virtualId}`;
+	const dir = options.dir ?? "skills";
+	return {
+		name: "tanstack-skills-catalog",
+		resolveId: (id) => id === virtualId ? resolved : void 0,
+		async load(id) {
+			if (id !== resolved) return void 0;
+			const catalog = await generateCatalog(dir, { maxDepth: options.maxDepth });
+			if (typeof this.addWatchFile === "function") for (const r of Array.isArray(dir) ? dir : [dir]) for (const d of await walkSkillDirs(nodeLister, r, { maxDepth: options.maxDepth })) this.addWatchFile(join(d.dir, "SKILL.md"));
+			return `export const catalog = ${JSON.stringify(catalog)} as const\n`;
+		}
+	};
+}
+//#endregion
+export { generateCatalog, skillDirectory, skillsCatalogPlugin };
+
+//# sourceMappingURL=index.js.map

package/dist/esm/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/node/index.ts"],"sourcesContent":["/**\n * `skillDirectory` — a filesystem-backed {@link SkillSource}. Lives behind the\n * `/node` subpath because it imports `node:fs`; the root export stays edge-safe\n * (Workers, browsers), mirroring `@tanstack/ai-code-mode-snippets/storage`.\n */\nimport { readFile, readdir, realpath, stat } from 'node:fs/promises'\nimport { basename, join, relative, sep } from 'node:path'\nimport { walkSkillDirs } from '../walk'\nimport { parseSkill, stripFrontmatter } from '../parse'\nimport { assertSafeResourcePath, stableHash } from '../util'\nimport type { Dirent } from 'node:fs'\nimport type { ListDir } from '../walk'\nimport type { GeneratedCatalog, GeneratedSkill } from '../static/index'\nimport type { SkillMetadata, SkillScriptRef, SkillSource } from '../types'\n\nconst RESOURCE_DIRS = ['references', 'assets']\nconst SCRIPT_DIR = 'scripts'\n\nexport interface SkillDirectoryOptions {\n  maxDepth?: number\n  /** default true — promote parse warnings to errors (see spec §7). */\n  strict?: boolean\n}\n\nconst nodeLister: ListDir = async (dir) => {\n  const ents = await readdir(dir, { withFileTypes: true })\n  return ents.map((e) => ({\n    name: e.name,\n    path: join(dir, e.name),\n    type: e.isDirectory() ? 'dir' : 'file',\n  }))\n}\n\n/** Recursively collect file paths under `dir`, relative to `root`. */\nasync function collectFiles(dir: string, root: string): Promise<Array<string>> {\n  let ents: Array<Dirent>\n  try {\n    ents = await readdir(dir, { withFileTypes: true })\n  } catch {\n    return []\n  }\n  const out: Array<string> = []\n  for (const e of ents) {\n    const full = join(dir, e.name)\n    if (e.isDirectory()) out.push(...(await collectFiles(full, root)))\n    else out.push(relative(root, full).replace(/\\\\/g, '/'))\n  }\n  return out\n}\n\nfunction posixRel(path: string): string {\n  return path.replace(/\\\\/g, '/')\n}\n\nfunction hasPrefix(rel: string, prefixes: Array<string>): boolean {\n  const n = posixRel(rel)\n  return prefixes.some((p) => n === p || n.startsWith(`${p}/`))\n}\n\nasync function resolveInside(dir: string, rel: string): Promise<string> {\n  const full = join(dir, rel)\n  const rootReal = await realpath(dir)\n  const fullReal = await realpath(full)\n  const prefix = rootReal.endsWith(sep) ? rootReal : rootReal + sep\n  if (fullReal !== rootReal && !fullReal.startsWith(prefix)) {\n    throw new Error(`unsafe resource path: \"${rel}\"`)\n  }\n  return fullReal\n}\n\nexport function skillDirectory(\n  root: string | Array<string>,\n  options: SkillDirectoryOptions = {},\n): SkillSource {\n  const roots = Array.isArray(root) ? root : [root]\n  const { maxDepth, strict = true } = options\n\n  /** Fresh scan of every root → parsed skill name → skill directory. First wins. */\n  const scan = async (): Promise<Map<string, string>> => {\n    const map = new Map<string, string>()\n    for (const r of roots) {\n      const dirs = await walkSkillDirs(nodeLister, r, { maxDepth })\n      for (const d of dirs) {\n        const raw = await readFile(join(d.dir, 'SKILL.md'), 'utf8').catch(\n          () => undefined,\n        )\n        if (raw === undefined) continue\n        try {\n          const parsed = parseSkill(raw, {\n            dirName: basename(d.dir),\n            strict,\n          })\n          if (!map.has(parsed.metadata.name)) {\n            map.set(parsed.metadata.name, d.dir)\n          }\n        } catch {\n          // Skip unparseable skills (same policy as list()).\n        }\n      }\n    }\n    return map\n  }\n\n  const dirOf = async (name: string): Promise<string> => {\n    const dir = (await scan()).get(name)\n    if (!dir)\n      throw new Error(`no skill named \"${name}\" under ${roots.join(', ')}`)\n    return dir\n  }\n\n  return {\n    revision: async () => {\n      const map = await scan()\n      const parts: Array<string> = []\n      for (const [name, dir] of [...map].sort()) {\n        const s = await stat(join(dir, 'SKILL.md')).catch(() => undefined)\n        parts.push(`${name}:${s?.mtimeMs ?? 0}:${s?.size ?? 0}`)\n      }\n      return stableHash(parts.join('|'))\n    },\n    list: async () => {\n      const map = await scan()\n      const out: Array<SkillMetadata> = []\n      for (const [, dir] of map) {\n        const raw = await readFile(join(dir, 'SKILL.md'), 'utf8').catch(\n          () => undefined,\n        )\n        if (raw === undefined) continue\n        try {\n          out.push(parseSkill(raw, { dirName: basename(dir), strict }).metadata)\n        } catch {\n          // Lenient: an unparseable skill is skipped, not fatal (spec §7).\n          // strict mode still throws inside parseSkill for warnings, but a\n          // genuinely broken file (no description) is always skipped.\n        }\n      }\n      return out\n    },\n    load: async (name) => readFile(join(await dirOf(name), 'SKILL.md'), 'utf8'),\n    listResources: async (name) => {\n      const dir = await dirOf(name)\n      const files: Array<string> = []\n      for (const sub of RESOURCE_DIRS) {\n        files.push(...(await collectFiles(join(dir, sub), dir)))\n      }\n      return files\n    },\n    readResource: async (name, path) => {\n      assertSafeResourcePath(path)\n      if (!hasPrefix(path, RESOURCE_DIRS)) {\n        throw new Error(\n          `resource path must be under references/ or assets/: \"${path}\"`,\n        )\n      }\n      const dir = await dirOf(name)\n      const fullReal = await resolveInside(dir, path)\n      if (hasPrefix(path, ['references'])) {\n        return readFile(fullReal, 'utf8')\n      }\n      return readFile(fullReal)\n    },\n    listScripts: async (name) => {\n      const dir = await dirOf(name)\n      const files = await collectFiles(join(dir, SCRIPT_DIR), dir)\n      return files.map(\n        (p): SkillScriptRef => ({\n          path: p,\n          executable: false,\n          reason: 'no-runtime',\n        }),\n      )\n    },\n    readScript: async (name, path) => {\n      assertSafeResourcePath(path)\n      if (!hasPrefix(path, [SCRIPT_DIR])) {\n        throw new Error(`script path must be under scripts/: \"${path}\"`)\n      }\n      const dir = await dirOf(name)\n      const fullReal = await resolveInside(dir, path)\n      const bytes = await readFile(fullReal)\n      return new Uint8Array(bytes)\n    },\n  }\n}\n\n/**\n * Read a skill directory tree into a plain {@link GeneratedCatalog} — the shape\n * `staticSkills` consumes. Used by the Vite plugin and directly available for\n * custom build scripts.\n */\nexport async function generateCatalog(\n  root: string | Array<string>,\n  options: SkillDirectoryOptions = {},\n): Promise<GeneratedCatalog> {\n  const roots = Array.isArray(root) ? root : [root]\n  const skills: Array<GeneratedSkill> = []\n  const seen = new Set<string>()\n  for (const r of roots) {\n    for (const { dir } of await walkSkillDirs(nodeLister, r, {\n      maxDepth: options.maxDepth,\n    })) {\n      const raw = await readFile(join(dir, 'SKILL.md'), 'utf8').catch(\n        () => undefined,\n      )\n      if (raw === undefined) continue\n      let meta\n      try {\n        meta = parseSkill(raw, {\n          dirName: basename(dir),\n          strict: options.strict ?? true,\n        }).metadata\n      } catch {\n        continue\n      }\n      if (seen.has(meta.name)) continue\n      seen.add(meta.name)\n      const resources: Record<string, string> = {}\n      for (const sub of RESOURCE_DIRS) {\n        for (const rel of await collectFiles(join(dir, sub), dir)) {\n          resources[rel] = await readFile(join(dir, rel), 'utf8').catch(\n            () => '',\n          )\n        }\n      }\n      skills.push({\n        name: meta.name,\n        description: meta.description,\n        body: stripFrontmatter(raw),\n        ...(meta.compatibility && { compatibility: meta.compatibility }),\n        ...(Object.keys(resources).length && { resources }),\n      })\n    }\n  }\n  skills.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))\n  const revision = stableHash(\n    skills.map((s) => `${s.name}:${stableHash(s.body)}`).join('|'),\n  )\n  return { revision, skills }\n}\n\n/** Structural Vite plugin (no `vite` type dependency). */\nexport interface SkillsCatalogPlugin {\n  name: string\n  resolveId: (id: string) => string | undefined\n  load: (\n    this: { addWatchFile?: (id: string) => void },\n    id: string,\n  ) => Promise<string | undefined>\n}\n\n/**\n * Vite plugin that globs `SKILL.md` under `dir` at build time and serves a\n * virtual module (default id `virtual:tanstack-skills`) exporting the catalog\n * `as const`. Consumers then wrap it with `staticSkills` for a literal-union of\n * skill names. The catalog is embedded as JSON, so the bundle hash tracks it.\n */\nexport function skillsCatalogPlugin(\n  options: { dir?: string; virtualId?: string; maxDepth?: number } = {},\n): SkillsCatalogPlugin {\n  const virtualId = options.virtualId ?? 'virtual:tanstack-skills'\n  const resolved = `\\0${virtualId}`\n  const dir = options.dir ?? 'skills'\n  return {\n    name: 'tanstack-skills-catalog',\n    resolveId: (id) => (id === virtualId ? resolved : undefined),\n    async load(this: { addWatchFile?: (id: string) => void }, id: string) {\n      if (id !== resolved) return undefined\n      const catalog = await generateCatalog(dir, { maxDepth: options.maxDepth })\n      if (typeof this.addWatchFile === 'function') {\n        for (const r of Array.isArray(dir) ? dir : [dir]) {\n          for (const d of await walkSkillDirs(nodeLister, r, {\n            maxDepth: options.maxDepth,\n          })) {\n            this.addWatchFile(join(d.dir, 'SKILL.md'))\n          }\n        }\n      }\n      return `export const catalog = ${JSON.stringify(catalog)} as const\\n`\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/esm/parse.d.ts

@@ -0,0 +1,25 @@
+import { SkillMetadata } from './types.js';
+export interface ParseWarning {
+    code: 'name-dir-mismatch' | 'name-too-long' | 'name-invalid-chars';
+    message: string;
+}
+export interface ParsedSkill {
+    metadata: SkillMetadata;
+    /** frontmatter stripped. */
+    body: string;
+    warnings: Array<ParseWarning>;
+}
+export declare class SkillParseError extends Error {
+    name: string;
+}
+/**
+ * Parse a `SKILL.md`. Throws {@link SkillParseError} for cases the spec says to
+ * skip (no frontmatter, missing description). Non-fatal issues are returned as
+ * `warnings`; `strict` turns them into throws.
+ */
+export declare function parseSkill(raw: string, opts?: {
+    dirName?: string;
+    strict?: boolean;
+}): ParsedSkill;
+/** Strip the frontmatter block, returning just the body. */
+export declare function stripFrontmatter(raw: string): string;

package/dist/esm/parse.js

@@ -0,0 +1,155 @@
+//#region src/parse.ts
+var SkillParseError = class extends Error {
+	name = "SkillParseError";
+};
+var NAME_RE = /^[a-z0-9-]+$/;
+/** Split leading `---` frontmatter from the body. Returns null if absent. */
+function splitFrontmatter(raw) {
+	const text = raw.replace(/^/, "");
+	const match = /^\s*---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/.exec(text);
+	if (!match) return null;
+	return {
+		frontmatter: match[1] ?? "",
+		body: match[2] ?? ""
+	};
+}
+/** Parse the flat frontmatter block into raw string/list/map values. */
+function parseBlock(frontmatter) {
+	const lines = frontmatter.split(/\r?\n/);
+	const out = {};
+	let i = 0;
+	const indentOf = (s) => s.length - s.trimStart().length;
+	while (i < lines.length) {
+		const line = lines[i];
+		if (line === void 0) break;
+		if (line.trim() === "" || line.trimStart().startsWith("#")) {
+			i++;
+			continue;
+		}
+		if (indentOf(line) > 0) {
+			i++;
+			continue;
+		}
+		const colon = line.indexOf(":");
+		if (colon === -1) {
+			i++;
+			continue;
+		}
+		const key = line.slice(0, colon).trim();
+		const value = line.slice(colon + 1).trim();
+		if (value === ">" || value === "|" || /^[>|][+-]?\d*$/.test(value)) {
+			const folded = value.startsWith(">");
+			const collected = [];
+			i++;
+			while (i < lines.length) {
+				const next = lines[i];
+				if (next === void 0) break;
+				if (next.trim() !== "" && indentOf(next) === 0) break;
+				collected.push(next);
+				i++;
+			}
+			const nonEmpty = collected.filter((l) => l.trim() !== "");
+			const minIndent = nonEmpty.length ? Math.min(...nonEmpty.map(indentOf)) : 0;
+			const stripped = collected.map((l) => l.slice(minIndent));
+			out[key] = folded ? stripped.join(" ").replace(/\s+/g, " ").trim() : stripped.join("\n").trim();
+			continue;
+		}
+		if (value === "") {
+			const items = [];
+			const map = {};
+			let j = i + 1;
+			while (j < lines.length) {
+				const next = lines[j];
+				if (next === void 0) break;
+				if (next.trim() === "") {
+					j++;
+					continue;
+				}
+				if (indentOf(next) === 0) break;
+				const t = next.trim();
+				if (t.startsWith("- ")) items.push(unquote(t.slice(2).trim()));
+				else {
+					const c = t.indexOf(":");
+					if (c === -1) break;
+					map[t.slice(0, c).trim()] = unquote(t.slice(c + 1).trim());
+				}
+				j++;
+			}
+			if (items.length) out[key] = items;
+			else if (Object.keys(map).length) out[key] = map;
+			else out[key] = "";
+			i = Math.max(j, i + 1);
+			continue;
+		}
+		if (value.startsWith("[") && value.endsWith("]")) {
+			out[key] = value.slice(1, -1).split(",").map((s) => unquote(s.trim())).filter((s) => s !== "");
+			i++;
+			continue;
+		}
+		out[key] = unquote(value);
+		i++;
+	}
+	return out;
+}
+function unquote(s) {
+	if (s.startsWith("\"") && s.endsWith("\"") || s.startsWith("'") && s.endsWith("'")) return s.slice(1, -1);
+	return s;
+}
+function asStringMap(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const out = {};
+	for (const [k, v] of Object.entries(value)) if (typeof v === "string") out[k] = v;
+	return Object.keys(out).length ? out : void 0;
+}
+/**
+* Parse a `SKILL.md`. Throws {@link SkillParseError} for cases the spec says to
+* skip (no frontmatter, missing description). Non-fatal issues are returned as
+* `warnings`; `strict` turns them into throws.
+*/
+function parseSkill(raw, opts = {}) {
+	const split = splitFrontmatter(raw);
+	if (!split) throw new SkillParseError("SKILL.md has no frontmatter block");
+	const block = parseBlock(split.frontmatter);
+	const name = typeof block.name === "string" ? block.name : void 0;
+	const description = typeof block.description === "string" ? block.description : void 0;
+	if (!description) throw new SkillParseError("SKILL.md is missing a `description`");
+	const warnings = [];
+	const effectiveName = name ?? opts.dirName ?? "";
+	if (name && opts.dirName && name !== opts.dirName) warnings.push({
+		code: "name-dir-mismatch",
+		message: `skill name "${name}" does not match directory "${opts.dirName}"`
+	});
+	if (effectiveName.length > 64) warnings.push({
+		code: "name-too-long",
+		message: `skill name "${effectiveName}" exceeds 64 characters`
+	});
+	if (effectiveName && !NAME_RE.test(effectiveName)) warnings.push({
+		code: "name-invalid-chars",
+		message: `skill name "${effectiveName}" contains characters outside [a-z0-9-]`
+	});
+	if (opts.strict && warnings.length) throw new SkillParseError(warnings.map((w) => w.message).join("; "));
+	return {
+		metadata: {
+			name: effectiveName,
+			description,
+			...typeof block.license === "string" && { license: block.license },
+			...typeof block.compatibility === "string" && { compatibility: block.compatibility },
+			...Array.isArray(block.allowedTools) && { allowedTools: block.allowedTools.filter((t) => typeof t === "string") },
+			...(() => {
+				const m = asStringMap(block.metadata);
+				return m ? { metadata: m } : {};
+			})()
+		},
+		body: split.body.trim(),
+		warnings
+	};
+}
+/** Strip the frontmatter block, returning just the body. */
+function stripFrontmatter(raw) {
+	const split = splitFrontmatter(raw);
+	return split ? split.body.trim() : raw.trim();
+}
+//#endregion
+export { SkillParseError, parseSkill, stripFrontmatter };
+
+//# sourceMappingURL=parse.js.map

package/dist/esm/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","names":[],"sources":["../../src/parse.ts"],"sourcesContent":["/**\n * Lenient `SKILL.md` frontmatter parsing (spec §7).\n *\n * Other clients emit malformed frontmatter — most commonly unquoted colons in\n * descriptions — so the default is lenient. We hand-roll a tiny parser rather\n * than pull in a YAML dependency: SKILL.md frontmatter is a flat key/value\n * block (plus block scalars for `description` and simple lists for\n * `allowedTools`), and taking `value = rest-of-line-after-first-colon` handles\n * the unquoted-colon case in a single pass — no quote-and-retry needed.\n *\n * | Condition            | Behavior                        |\n * |----------------------|---------------------------------|\n * | name/dir mismatch    | warn, load                      |\n * | name over 64 chars   | warn, load                      |\n * | invalid name chars   | warn, load                      |\n * | missing `description`| throw (caller skips)            |\n * | no frontmatter       | throw (caller skips)            |\n *\n * `strict: true` promotes every warning to a thrown error.\n */\nimport type { SkillMetadata } from './types'\n\nexport interface ParseWarning {\n  code: 'name-dir-mismatch' | 'name-too-long' | 'name-invalid-chars'\n  message: string\n}\n\nexport interface ParsedSkill {\n  metadata: SkillMetadata\n  /** frontmatter stripped. */\n  body: string\n  warnings: Array<ParseWarning>\n}\n\nexport class SkillParseError extends Error {\n  override name = 'SkillParseError'\n}\n\nconst NAME_RE = /^[a-z0-9-]+$/\n\n/** Split leading `---` frontmatter from the body. Returns null if absent. */\nfunction splitFrontmatter(\n  raw: string,\n): { frontmatter: string; body: string } | null {\n  // Tolerate a BOM and leading blank lines before the opening fence.\n  const text = raw.replace(/^/, '')\n  const match = /^\\s*---\\r?\\n([\\s\\S]*?)\\r?\\n---[ \\t]*(?:\\r?\\n([\\s\\S]*))?$/.exec(\n    text,\n  )\n  if (!match) return null\n  return { frontmatter: match[1] ?? '', body: match[2] ?? '' }\n}\n\n/** Parse the flat frontmatter block into raw string/list/map values. */\nfunction parseBlock(frontmatter: string): Record<string, unknown> {\n  const lines = frontmatter.split(/\\r?\\n/)\n  const out: Record<string, unknown> = {}\n  let i = 0\n\n  const indentOf = (s: string) => s.length - s.trimStart().length\n\n  while (i < lines.length) {\n    const line = lines[i]\n    if (line === undefined) break\n    if (line.trim() === '' || line.trimStart().startsWith('#')) {\n      i++\n      continue\n    }\n    // Top-level keys are unindented.\n    if (indentOf(line) > 0) {\n      i++\n      continue\n    }\n    const colon = line.indexOf(':')\n    if (colon === -1) {\n      i++\n      continue\n    }\n    const key = line.slice(0, colon).trim()\n    const value = line.slice(colon + 1).trim()\n\n    // Block scalar: `>` (folded) or `|` (literal), with optional chomp/indent.\n    if (value === '>' || value === '|' || /^[>|][+-]?\\d*$/.test(value)) {\n      const folded = value.startsWith('>')\n      const collected: Array<string> = []\n      i++\n      while (i < lines.length) {\n        const next = lines[i]\n        if (next === undefined) break\n        if (next.trim() !== '' && indentOf(next) === 0) break\n        collected.push(next)\n        i++\n      }\n      // Strip the common leading indentation of the block.\n      const nonEmpty = collected.filter((l) => l.trim() !== '')\n      const minIndent = nonEmpty.length\n        ? Math.min(...nonEmpty.map(indentOf))\n        : 0\n      const stripped = collected.map((l) => l.slice(minIndent))\n      out[key] = folded\n        ? stripped.join(' ').replace(/\\s+/g, ' ').trim()\n        : stripped.join('\\n').trim()\n      continue\n    }\n\n    // Empty value → indented children: a block list (`- x`) or a nested map\n    // (`k: v`), one level deep.\n    if (value === '') {\n      const items: Array<string> = []\n      const map: Record<string, string> = {}\n      let j = i + 1\n      while (j < lines.length) {\n        const next = lines[j]\n        if (next === undefined) break\n        if (next.trim() === '') {\n          j++\n          continue\n        }\n        if (indentOf(next) === 0) break\n        const t = next.trim()\n        if (t.startsWith('- ')) {\n          items.push(unquote(t.slice(2).trim()))\n        } else {\n          const c = t.indexOf(':')\n          if (c === -1) break\n          map[t.slice(0, c).trim()] = unquote(t.slice(c + 1).trim())\n        }\n        j++\n      }\n      if (items.length) out[key] = items\n      else if (Object.keys(map).length) out[key] = map\n      else out[key] = ''\n      i = Math.max(j, i + 1)\n      continue\n    }\n\n    // Inline list `[a, b]`.\n    if (value.startsWith('[') && value.endsWith(']')) {\n      out[key] = value\n        .slice(1, -1)\n        .split(',')\n        .map((s) => unquote(s.trim()))\n        .filter((s) => s !== '')\n      i++\n      continue\n    }\n\n    out[key] = unquote(value)\n    i++\n  }\n  return out\n}\n\nfunction unquote(s: string): string {\n  if (\n    (s.startsWith('\"') && s.endsWith('\"')) ||\n    (s.startsWith(\"'\") && s.endsWith(\"'\"))\n  ) {\n    return s.slice(1, -1)\n  }\n  return s\n}\n\nfunction asStringMap(value: unknown): Record<string, string> | undefined {\n  if (typeof value !== 'object' || value === null) return undefined\n  const out: Record<string, string> = {}\n  for (const [k, v] of Object.entries(value)) {\n    if (typeof v === 'string') out[k] = v\n  }\n  return Object.keys(out).length ? out : undefined\n}\n\n/**\n * Parse a `SKILL.md`. Throws {@link SkillParseError} for cases the spec says to\n * skip (no frontmatter, missing description). Non-fatal issues are returned as\n * `warnings`; `strict` turns them into throws.\n */\nexport function parseSkill(\n  raw: string,\n  opts: { dirName?: string; strict?: boolean } = {},\n): ParsedSkill {\n  const split = splitFrontmatter(raw)\n  if (!split) {\n    throw new SkillParseError('SKILL.md has no frontmatter block')\n  }\n  const block = parseBlock(split.frontmatter)\n\n  const name = typeof block.name === 'string' ? block.name : undefined\n  const description =\n    typeof block.description === 'string' ? block.description : undefined\n\n  if (!description) {\n    throw new SkillParseError('SKILL.md is missing a `description`')\n  }\n\n  const warnings: Array<ParseWarning> = []\n  const effectiveName = name ?? opts.dirName ?? ''\n\n  if (name && opts.dirName && name !== opts.dirName) {\n    warnings.push({\n      code: 'name-dir-mismatch',\n      message: `skill name \"${name}\" does not match directory \"${opts.dirName}\"`,\n    })\n  }\n  if (effectiveName.length > 64) {\n    warnings.push({\n      code: 'name-too-long',\n      message: `skill name \"${effectiveName}\" exceeds 64 characters`,\n    })\n  }\n  if (effectiveName && !NAME_RE.test(effectiveName)) {\n    warnings.push({\n      code: 'name-invalid-chars',\n      message: `skill name \"${effectiveName}\" contains characters outside [a-z0-9-]`,\n    })\n  }\n\n  if (opts.strict && warnings.length) {\n    throw new SkillParseError(warnings.map((w) => w.message).join('; '))\n  }\n\n  const metadata: SkillMetadata = {\n    name: effectiveName,\n    description,\n    ...(typeof block.license === 'string' && { license: block.license }),\n    ...(typeof block.compatibility === 'string' && {\n      compatibility: block.compatibility,\n    }),\n    ...(Array.isArray(block.allowedTools) && {\n      allowedTools: block.allowedTools.filter(\n        (t): t is string => typeof t === 'string',\n      ),\n    }),\n    ...((): { metadata?: Record<string, string> } => {\n      const m = asStringMap(block.metadata)\n      return m ? { metadata: m } : {}\n    })(),\n  }\n\n  return { metadata, body: split.body.trim(), warnings }\n}\n\n/** Strip the frontmatter block, returning just the body. */\nexport function stripFrontmatter(raw: string): string {\n  const split = splitFrontmatter(raw)\n  return split ? split.body.trim() : raw.trim()\n}\n"],"mappings":"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"}

package/dist/esm/sources/inline.d.ts

@@ -0,0 +1,9 @@
+import { SkillSource } from '../types.js';
+export interface InlineSkillConfig {
+    name: string;
+    description: string;
+    instructions: string;
+    resources?: Record<string, string | (() => string | Promise<string>)>;
+    compatibility?: string;
+}
+export declare function inlineSkill(config: InlineSkillConfig): SkillSource;

package/dist/esm/sources/inline.js

@@ -0,0 +1,48 @@
+import { stableHash } from "../util.js";
+import { validateSkill } from "../validate.js";
+//#region src/sources/inline.ts
+/**
+* `inlineSkill` — an edge-safe {@link SkillSource} for a single skill defined
+* next to app code, in a DB row, or per-session/per-tenant. Resource values may
+* be thunks, evaluated at read time.
+*/
+function inlineSkill(config) {
+	const metadata = {
+		name: config.name,
+		description: config.description,
+		...config.compatibility && { compatibility: config.compatibility }
+	};
+	const lint = validateSkill(metadata);
+	if (!lint.ok) throw new Error(`inlineSkill "${config.name}": ${lint.issues.map((i) => i.message).join("; ")}`);
+	const resourcePaths = Object.keys(config.resources ?? {});
+	const revision = stableHash(JSON.stringify({
+		metadata,
+		instructions: config.instructions,
+		resources: resourcePaths
+	}));
+	const assertName = (name) => {
+		if (name !== config.name) throw new Error(`inlineSkill has no skill named "${name}"`);
+	};
+	return {
+		revision: () => Promise.resolve(revision),
+		list: () => Promise.resolve([metadata]),
+		load: async (name) => {
+			assertName(name);
+			return config.instructions;
+		},
+		listResources: async (name) => {
+			assertName(name);
+			return resourcePaths;
+		},
+		readResource: async (name, path) => {
+			assertName(name);
+			const value = config.resources?.[path];
+			if (value === void 0) throw new Error(`skill "${name}" has no resource "${path}"`);
+			return typeof value === "function" ? await value() : value;
+		}
+	};
+}
+//#endregion
+export { inlineSkill };
+
+//# sourceMappingURL=inline.js.map

package/dist/esm/sources/inline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline.js","names":[],"sources":["../../../src/sources/inline.ts"],"sourcesContent":["/**\n * `inlineSkill` — an edge-safe {@link SkillSource} for a single skill defined\n * next to app code, in a DB row, or per-session/per-tenant. Resource values may\n * be thunks, evaluated at read time.\n */\nimport { stableHash } from '../util'\nimport { validateSkill } from '../validate'\nimport type { SkillMetadata, SkillSource } from '../types'\n\nexport interface InlineSkillConfig {\n  name: string\n  description: string\n  instructions: string\n  resources?: Record<string, string | (() => string | Promise<string>)>\n  compatibility?: string\n}\n\nexport function inlineSkill(config: InlineSkillConfig): SkillSource {\n  const metadata: SkillMetadata = {\n    name: config.name,\n    description: config.description,\n    ...(config.compatibility && { compatibility: config.compatibility }),\n  }\n  const lint = validateSkill(metadata)\n  if (!lint.ok) {\n    throw new Error(\n      `inlineSkill \"${config.name}\": ${lint.issues.map((i) => i.message).join('; ')}`,\n    )\n  }\n  const resourcePaths = Object.keys(config.resources ?? {})\n  const revision = stableHash(\n    JSON.stringify({\n      metadata,\n      instructions: config.instructions,\n      resources: resourcePaths,\n    }),\n  )\n\n  const assertName = (name: string) => {\n    if (name !== config.name) {\n      throw new Error(`inlineSkill has no skill named \"${name}\"`)\n    }\n  }\n\n  return {\n    revision: () => Promise.resolve(revision),\n    list: () => Promise.resolve([metadata]),\n    // Async so an unknown-name throw surfaces as a rejected promise.\n    load: async (name) => {\n      assertName(name)\n      return config.instructions\n    },\n    listResources: async (name) => {\n      assertName(name)\n      return resourcePaths\n    },\n    readResource: async (name, path) => {\n      assertName(name)\n      const value = config.resources?.[path]\n      if (value === undefined) {\n        throw new Error(`skill \"${name}\" has no resource \"${path}\"`)\n      }\n      return typeof value === 'function' ? await value() : value\n    },\n  }\n}\n"],"mappings":";;;;;;;;AAiBA,SAAgB,YAAY,QAAwC;CAClE,MAAM,WAA0B;EAC9B,MAAM,OAAO;EACb,aAAa,OAAO;EACpB,GAAI,OAAO,iBAAiB,EAAE,eAAe,OAAO,cAAc;CACpE;CACA,MAAM,OAAO,cAAc,QAAQ;CACnC,IAAI,CAAC,KAAK,IACR,MAAM,IAAI,MACR,gBAAgB,OAAO,KAAK,KAAK,KAAK,OAAO,KAAK,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,IAAI,GAC9E;CAEF,MAAM,gBAAgB,OAAO,KAAK,OAAO,aAAa,CAAC,CAAC;CACxD,MAAM,WAAW,WACf,KAAK,UAAU;EACb;EACA,cAAc,OAAO;EACrB,WAAW;CACb,CAAC,CACH;CAEA,MAAM,cAAc,SAAiB;EACnC,IAAI,SAAS,OAAO,MAClB,MAAM,IAAI,MAAM,mCAAmC,KAAK,EAAE;CAE9D;CAEA,OAAO;EACL,gBAAgB,QAAQ,QAAQ,QAAQ;EACxC,YAAY,QAAQ,QAAQ,CAAC,QAAQ,CAAC;EAEtC,MAAM,OAAO,SAAS;GACpB,WAAW,IAAI;GACf,OAAO,OAAO;EAChB;EACA,eAAe,OAAO,SAAS;GAC7B,WAAW,IAAI;GACf,OAAO;EACT;EACA,cAAc,OAAO,MAAM,SAAS;GAClC,WAAW,IAAI;GACf,MAAM,QAAQ,OAAO,YAAY;GACjC,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,MAAM,UAAU,KAAK,qBAAqB,KAAK,EAAE;GAE7D,OAAO,OAAO,UAAU,aAAa,MAAM,MAAM,IAAI;EACvD;CACF;AACF"}

package/dist/esm/static/index.d.ts

@@ -0,0 +1,17 @@
+import { SkillSource } from '../types.js';
+export interface GeneratedSkill<T extends string = string> {
+    name: T;
+    description: string;
+    /** raw SKILL.md body, frontmatter stripped at generation time. */
+    body: string;
+    compatibility?: string;
+    /** embedded resource files, path → utf8 contents. */
+    resources?: Record<string, string>;
+}
+export interface GeneratedCatalog<T extends string = string> {
+    revision: string;
+    skills: ReadonlyArray<GeneratedSkill<T>>;
+}
+export declare function staticSkills<T extends string>(catalog: GeneratedCatalog<T>): SkillSource & {
+    names: ReadonlyArray<T>;
+};

package/dist/esm/static/index.js

@@ -0,0 +1,29 @@
+//#region src/static/index.ts
+function staticSkills(catalog) {
+	const byName = new Map(catalog.skills.map((s) => [s.name, s]));
+	const get = (name) => {
+		const s = byName.get(name);
+		if (!s) throw new Error(`static catalog has no skill named "${name}"`);
+		return s;
+	};
+	return {
+		names: catalog.skills.map((s) => s.name),
+		revision: () => Promise.resolve(catalog.revision),
+		list: () => Promise.resolve(catalog.skills.map((s) => ({
+			name: s.name,
+			description: s.description,
+			...s.compatibility && { compatibility: s.compatibility }
+		}))),
+		load: async (name) => get(name).body,
+		listResources: async (name) => Object.keys(get(name).resources ?? {}),
+		readResource: async (name, path) => {
+			const value = get(name).resources?.[path];
+			if (value === void 0) throw new Error(`skill "${name}" has no resource "${path}"`);
+			return value;
+		}
+	};
+}
+//#endregion
+export { staticSkills };
+
+//# sourceMappingURL=index.js.map

package/dist/esm/static/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/static/index.ts"],"sourcesContent":["/**\n * `staticSkills` — wrap a build-time-generated catalog as a {@link SkillSource}.\n *\n * Edge-safe: this file imports no `node:*` modules. The Vite plugin that GLOBS\n * `skills/**​/SKILL.md` and emits the catalog lives in `@tanstack/ai-skills/node`\n * (it needs `node:fs`); the emitted catalog is plain data consumed here.\n *\n * The generated catalog is `as const`, so `T` is the literal union of skill\n * names — which flows into `load_skill`'s enum, the constraint the spec\n * recommends, obtained at build time rather than runtime.\n */\nimport type { SkillMetadata, SkillSource } from '../types'\n\nexport interface GeneratedSkill<T extends string = string> {\n  name: T\n  description: string\n  /** raw SKILL.md body, frontmatter stripped at generation time. */\n  body: string\n  compatibility?: string\n  /** embedded resource files, path → utf8 contents. */\n  resources?: Record<string, string>\n}\n\nexport interface GeneratedCatalog<T extends string = string> {\n  revision: string\n  skills: ReadonlyArray<GeneratedSkill<T>>\n}\n\nexport function staticSkills<T extends string>(\n  catalog: GeneratedCatalog<T>,\n): SkillSource & { names: ReadonlyArray<T> } {\n  const byName = new Map(catalog.skills.map((s) => [s.name, s]))\n  const get = (name: string): GeneratedSkill<T> => {\n    const s = byName.get(name as T)\n    if (!s) throw new Error(`static catalog has no skill named \"${name}\"`)\n    return s\n  }\n\n  return {\n    names: catalog.skills.map((s) => s.name),\n    revision: () => Promise.resolve(catalog.revision),\n    list: () =>\n      Promise.resolve(\n        catalog.skills.map(\n          (s): SkillMetadata => ({\n            name: s.name,\n            description: s.description,\n            ...(s.compatibility && { compatibility: s.compatibility }),\n          }),\n        ),\n      ),\n    // Methods are async so a missing-skill throw surfaces as a rejected\n    // promise (what callers `await`), not a synchronous throw.\n    load: async (name) => get(name).body,\n    listResources: async (name) => Object.keys(get(name).resources ?? {}),\n    readResource: async (name, path) => {\n      const value = get(name).resources?.[path]\n      if (value === undefined) {\n        throw new Error(`skill \"${name}\" has no resource \"${path}\"`)\n      }\n      return value\n    },\n  }\n}\n"],"mappings":";AA4BA,SAAgB,aACd,SAC2C;CAC3C,MAAM,SAAS,IAAI,IAAI,QAAQ,OAAO,KAAK,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7D,MAAM,OAAO,SAAoC;EAC/C,MAAM,IAAI,OAAO,IAAI,IAAS;EAC9B,IAAI,CAAC,GAAG,MAAM,IAAI,MAAM,sCAAsC,KAAK,EAAE;EACrE,OAAO;CACT;CAEA,OAAO;EACL,OAAO,QAAQ,OAAO,KAAK,MAAM,EAAE,IAAI;EACvC,gBAAgB,QAAQ,QAAQ,QAAQ,QAAQ;EAChD,YACE,QAAQ,QACN,QAAQ,OAAO,KACZ,OAAsB;GACrB,MAAM,EAAE;GACR,aAAa,EAAE;GACf,GAAI,EAAE,iBAAiB,EAAE,eAAe,EAAE,cAAc;EAC1D,EACF,CACF;EAGF,MAAM,OAAO,SAAS,IAAI,IAAI,CAAC,CAAC;EAChC,eAAe,OAAO,SAAS,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,aAAa,CAAC,CAAC;EACpE,cAAc,OAAO,MAAM,SAAS;GAClC,MAAM,QAAQ,IAAI,IAAI,CAAC,CAAC,YAAY;GACpC,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,MAAM,UAAU,KAAK,qBAAqB,KAAK,EAAE;GAE7D,OAAO;EACT;CACF;AACF"}

package/dist/esm/testing/index.d.ts

@@ -0,0 +1,2 @@
+import { SkillSource } from '../types.js';
+export declare function runSkillSourceConformance(factory: () => SkillSource | Promise<SkillSource>, label?: string): void;

package/dist/esm/testing/index.js

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+//#region src/testing/index.ts
+/**
+* `runSkillSourceConformance` — the real deliverable for third-party adapters.
+* Since adapter code is frequently LLM-generated, this suite (not prose) is what
+* makes a new `SkillSource` safe to ship.
+*
+* The factory must return a source seeded with this fixed fixture contract:
+*
+*   - skill `alpha`: description non-empty; resource `references/note.md` whose
+*     contents are exactly `hello`; script `scripts/run.py` whose bytes decode
+*     to `print(1)` (only if the source supports scripts).
+*   - skill `beta`: description non-empty; no resources required.
+*
+* Sources that cannot represent a tier (resources/scripts) simply omit the
+* corresponding methods — those cases are skipped, not failed.
+*/
+var dec = (v) => typeof v === "string" ? v : new TextDecoder().decode(v);
+function runSkillSourceConformance(factory, label = "SkillSource") {
+	describe(`conformance: ${label}`, () => {
+		it("lists skills with a name and description", async () => {
+			const skills = await (await factory()).list();
+			const names = skills.map((s) => s.name);
+			expect(names).toContain("alpha");
+			expect(names).toContain("beta");
+			for (const s of skills) {
+				expect(s.name).toBeTruthy();
+				expect(s.description).toBeTruthy();
+			}
+		});
+		it("loads a known skill body", async () => {
+			const body = await (await factory()).load("alpha");
+			expect(typeof body).toBe("string");
+			expect(body.length).toBeGreaterThan(0);
+		});
+		it("throws (not returns empty) for a missing skill name", async () => {
+			const source = await factory();
+			await expect(source.load("does-not-exist")).rejects.toThrow();
+		});
+		it("has a stable revision across identical content", async () => {
+			const rev = (await factory()).revision;
+			if (!rev) return;
+			const a = await rev();
+			const b = await rev();
+			expect(a).toBe(b);
+			const other = await factory();
+			if (other.revision) expect(await other.revision()).toBe(a);
+		});
+		it("serves concurrent list() consistently", async () => {
+			const source = await factory();
+			const [a, b] = await Promise.all([source.list(), source.list()]);
+			expect(a.map((s) => s.name).sort()).toEqual(b.map((s) => s.name).sort());
+		});
+		it("reads a bundled resource and rejects path traversal", async () => {
+			const { listResources, readResource } = await factory();
+			if (!listResources || !readResource) return;
+			const resources = await listResources("alpha");
+			expect(resources).toContain("references/note.md");
+			const value = await readResource("alpha", "references/note.md");
+			expect(dec(value).trimEnd()).toBe("hello");
+			await expect(readResource("alpha", "../../etc/passwd")).rejects.toThrow();
+		});
+		it("returns script bytes correctly", async () => {
+			const source = await factory();
+			if (!source.listScripts || !source.readScript) return;
+			const ref = (await source.listScripts("alpha")).find((s) => s.path === "scripts/run.py");
+			if (!ref) return;
+			expect(ref.executable).toBe(false);
+			const bytes = await source.readScript("alpha", "scripts/run.py");
+			expect(bytes).toBeInstanceOf(Uint8Array);
+			expect(dec(bytes)).toContain("print(1)");
+		});
+	});
+}
+//#endregion
+export { runSkillSourceConformance };
+
+//# sourceMappingURL=index.js.map