@stage-labs/metro 0.1.0-beta.28 → 0.1.0-beta.280

package/runtime/node_modules/@metro-labs/daemon/src/claude/github-fetch.ts

@@ -0,0 +1,160 @@
+import { createHash } from 'node:crypto';
+import { isRecord } from '@metro-labs/core/is-record';
+import { SKILL_COMMIT, SKILL_FILE_MAX, SKILL_FILES_MAX, SKILL_TOTAL_MAX, skillPath, type SkillSource } from '@metro-labs/core/skill-source';
+
+export class GitHubFailure extends Error {
+  constructor(message: string, readonly retryAt = Date.now() + 60_000, readonly rateLimited = false) { super(message); }
+}
+
+export interface GitHubSnapshot {
+  repositoryId: number;
+  commit: string;
+  etag: string | null;
+  files: Map<string, Buffer>;
+  executables?: string[];
+}
+
+interface Entry { path: string; mode: string; type: string; sha: string; size: number }
+type Request = (url: string, init: RequestInit) => Promise<Response>;
+const API = 'https://api.github.com/repos/';
+const RESPONSE_MAX = 2 * 1024 * 1024;
+
+async function boundedJson(response: Response, text: boolean): Promise<unknown> {
+  if (response.body === null) throw new GitHubFailure('GitHub returned an empty response.');
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let bytes = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytes += value.byteLength;
+      if (bytes > RESPONSE_MAX) throw new GitHubFailure('GitHub returned too much data. Choose a smaller skills folder.');
+      chunks.push(value);
+    }
+    const body = Buffer.concat(chunks).toString('utf8');
+    return text ? body.trim() : JSON.parse(body) as unknown;
+  } finally { await reader.cancel().catch(() => undefined); }
+}
+
+function refused(response: Response): GitHubFailure {
+  const retry = Number(response.headers.get('retry-after'));
+  const reset = Number(response.headers.get('x-ratelimit-reset')) * 1000;
+  if (response.status === 429 || (response.status === 403 && (response.headers.get('x-ratelimit-remaining') === '0' || retry > 0))) {
+    return new GitHubFailure('GitHub rate limit reached. Sync will retry later.', Math.max(Date.now() + 60_000, Date.now() + (Number.isFinite(retry) ? retry * 1000 : 0), Number.isFinite(reset) ? reset : 0), true);
+  }
+  if ([401, 403, 404].includes(response.status)) return new GitHubFailure('GitHub access was refused. Check the repository, ref, token expiry and organization approval. The loaded skills are kept.', Date.now() + 15 * 60_000);
+  return new GitHubFailure('GitHub could not provide the skills. The loaded skills are kept.');
+}
+
+function headers(token: string, etag: string | null | undefined, shaOnly: boolean): Record<string, string> {
+  return { Authorization: `Bearer ${token}`, Accept: shaOnly ? 'application/vnd.github.sha' : 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', ...(etag ? { 'If-None-Match': etag } : {}) };
+}
+
+export class GitHubReader {
+  private readonly base: string;
+  private count = 0;
+  private readonly signal = AbortSignal.timeout(120_000);
+  constructor(private readonly source: SkillSource, private readonly token: string, private readonly request: Request = fetch) {
+    this.base = `${API}${source.repository}`;
+  }
+
+  private async get(path: string, etag?: string | null, shaOnly = false): Promise<{ data: unknown; etag: string | null; unchanged: boolean }> {
+    if (++this.count > SKILL_FILES_MAX + 12) throw new GitHubFailure('The skills folder needs too many GitHub requests.');
+    let response: Response;
+    try {
+      response = await this.request(`${this.base}${path}`, {
+        headers: headers(this.token, etag, shaOnly),
+        redirect: 'manual', signal: AbortSignal.any([this.signal, AbortSignal.timeout(20_000)]),
+      });
+    } catch { throw new GitHubFailure('GitHub is unreachable. The loaded skills are kept.'); }
+    if (response.status === 304) return { data: null, etag: etag ?? null, unchanged: true };
+    if (!response.ok) { await response.body?.cancel(); throw refused(response); }
+    try { return { data: await boundedJson(response, shaOnly), etag: response.headers.get('etag'), unchanged: false }; }
+    catch (err) { if (err instanceof GitHubFailure) throw err; throw new GitHubFailure('GitHub returned invalid skills data.'); }
+  }
+
+  private async tree(sha: string, recursive: boolean): Promise<Entry[]> {
+    const { data } = await this.get(`/git/trees/${sha}${recursive ? '?recursive=1' : ''}`);
+    if (!isRecord(data) || data.truncated !== false || !Array.isArray(data.tree) || data.tree.length > 4096) throw new GitHubFailure('The GitHub tree is incomplete or too large. Choose a smaller skills folder.');
+    return data.tree.map((raw: unknown) => {
+      if (!isRecord(raw) || typeof raw.path !== 'string' || typeof raw.mode !== 'string' || typeof raw.type !== 'string' || typeof raw.sha !== 'string' || !SKILL_COMMIT.test(raw.sha)) throw new GitHubFailure('GitHub returned an invalid tree.');
+      return { path: raw.path, mode: raw.mode, type: raw.type, sha: raw.sha, size: typeof raw.size === 'number' ? raw.size : 0 };
+    });
+  }
+
+  private async folder(tree: string): Promise<string> {
+    let sha = tree;
+    for (const segment of this.source.folder.split('/').filter(Boolean)) {
+      const entry = (await this.tree(sha, false)).find((row) => row.path === segment);
+      if (entry?.mode !== '040000' || entry.type !== 'tree') throw new GitHubFailure('The selected skills folder is missing or is not a regular directory.');
+      sha = entry.sha;
+    }
+    return sha;
+  }
+
+  private async blob(entry: Entry): Promise<Buffer> {
+    const { data } = await this.get(`/git/blobs/${entry.sha}`);
+    if (!isRecord(data) || data.encoding !== 'base64' || typeof data.content !== 'string' || data.size !== entry.size) throw new GitHubFailure('GitHub returned an invalid skill file.');
+    const encoded = data.content.replace(/\n/g, '');
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded)) throw new GitHubFailure('GitHub returned an invalid skill file.');
+    const bytes = Buffer.from(encoded, 'base64');
+    const hash = createHash('sha1').update(`blob ${bytes.byteLength}\0`).update(bytes).digest('hex');
+    if (bytes.byteLength !== entry.size || hash !== entry.sha) throw new GitHubFailure('A skill file has an unexpected size or Git object hash.');
+    return bytes;
+  }
+
+  private async repository(expected: number | null): Promise<number> {
+    const repo = (await this.get('')).data;
+    if (!isRecord(repo) || typeof repo.id !== 'number' || typeof repo.full_name !== 'string' || repo.full_name.toLowerCase() !== this.source.repository.toLowerCase() || (expected !== null && repo.id !== expected)) throw new GitHubFailure('The GitHub repository identity changed. Reconnect it explicitly.');
+    return repo.id;
+  }
+
+  async snapshot(repositoryId: number | null, commit: string | null, etag: string | null): Promise<GitHubSnapshot | null> {
+    const id = await this.repository(repositoryId);
+    const resolved = await this.get(`/commits/${encodeURIComponent(this.source.ref)}`, etag, true);
+    if (resolved.unchanged) return null;
+    if (typeof resolved.data !== 'string' || !SKILL_COMMIT.test(resolved.data)) throw new GitHubFailure('GitHub did not resolve an immutable commit.');
+    if (resolved.data === commit) return null;
+    const data = immutableCommit((await this.get(`/git/commits/${resolved.data}`)).data);
+    if (data.sha !== resolved.data) throw new GitHubFailure('GitHub returned a different commit.');
+    const entries = checkedEntries(await this.tree(await this.folder(data.tree), true));
+    const files = await this.blobs(entries);
+    return { repositoryId: id, commit: data.sha, etag: resolved.etag, files, executables: entries.filter((entry) => entry.mode === '100755').map((entry) => entry.path) };
+  }
+
+  private async blobs(entries: Entry[]): Promise<Map<string, Buffer>> {
+    const queue = [...entries];
+    const files = new Map<string, Buffer>();
+    const worker = async (): Promise<void> => {
+      for (let entry = queue.shift(); entry !== undefined; entry = queue.shift()) files.set(entry.path, await this.blob(entry));
+    };
+    try { await Promise.all(Array.from({ length: Math.min(4, queue.length) }, worker)); }
+    catch (err) { queue.length = 0; throw err; }
+    return files;
+  }
+}
+
+function immutableCommit(data: unknown): { sha: string; tree: string } {
+  if (!isRecord(data) || typeof data.sha !== 'string' || !SKILL_COMMIT.test(data.sha) || !isRecord(data.tree) || typeof data.tree.sha !== 'string' || !SKILL_COMMIT.test(data.tree.sha)) throw new GitHubFailure('GitHub did not resolve an immutable commit.');
+  return { sha: data.sha, tree: data.tree.sha };
+}
+
+function regularFile(entry: Entry): void {
+  if (entry.type !== 'blob' || !['100644', '100755'].includes(entry.mode)) throw new GitHubFailure('Symlinks, submodules and special files are not supported in skills.');
+  if (!skillPath(entry.path) || entry.size < 0 || entry.size > SKILL_FILE_MAX || !Number.isInteger(entry.size)) throw new GitHubFailure('A skills path or file size is not supported. Use skill-name/SKILL.md and regular resources, up to 256 KiB each.');
+}
+
+function checkedEntries(entries: Entry[]): Entry[] {
+  const files: Entry[] = [];
+  let total = 0;
+  for (const entry of entries) {
+    if (entry.mode === '040000' && entry.type === 'tree') continue;
+    regularFile(entry);
+    total += entry.size;
+    files.push(entry);
+  }
+  if (files.length > SKILL_FILES_MAX || total > SKILL_TOTAL_MAX) throw new GitHubFailure('Skills exceed 256 files or 8 MiB.');
+  if (new Set(files.map((entry) => entry.path.toLowerCase())).size !== files.length) throw new GitHubFailure('Skills contain duplicate file paths.');
+  return files;
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/github-skills.ts

@@ -0,0 +1,257 @@
+import { existsSync, readFileSync as readLocal, statSync as statLocal } from 'node:fs';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { writeSecure } from '@metro-labs/core/secure-fs';
+import { SKILL_HASH, SKILL_MANIFEST_MAX, skillGeneration, skillRelease, skillSourceRoot, type SkillGeneration } from '@metro-labs/core/skill-source';
+import { ApiError } from '@metro-labs/http/api-error';
+import { readFileSync, statSync } from '../agent-user/agent-fs.js';
+import { receiveHomeFile, writeHomeText } from '../agent-user/home-fs.js';
+import { agentsDir } from '../agents/files.js';
+import { claudeDir } from './files.js';
+import { readSetupState } from './setup-state.js';
+import { GitHubFailure, GitHubReader } from './github-fetch.js';
+import { githubSource, validatedGeneration } from './github-validate.js';
+import type { ClaudeSkill } from './skills.js';
+
+type Configuration = ReturnType<typeof githubSource>;
+interface Stored {
+  source: Configuration | null;
+  prepared: SkillGeneration | null;
+  etag: string | null;
+  checkedAt: string | null;
+  retryAt: number;
+  problem: string | null;
+  rateLimit: number;
+  repositoryId: number | null;
+}
+export interface GitHubSkillsDeps {
+  agents: string;
+  claude: string;
+  sdk(): boolean;
+  request?: (url: string, init: RequestInit) => Promise<Response>;
+}
+const EMPTY: Stored = { source: null, prepared: null, etag: null, checkedAt: null, retryAt: 0, problem: null, rateLimit: 0, repositoryId: null };
+const savedString = (value: unknown): string | null => typeof value === 'string' ? value : null;
+const savedNumber = (value: unknown): number => typeof value === 'number' && Number.isFinite(value) ? value : 0;
+
+function readStored(path: string): Stored {
+  if (!existsSync(path)) return { ...EMPTY };
+  try {
+    if (statLocal(path).size > SKILL_MANIFEST_MAX * 2) throw new Error('size');
+    const raw: unknown = JSON.parse(readLocal(path, 'utf8'));
+    if (!isRecord(raw)) throw new Error('shape');
+    return {
+      source: raw.source === null ? null : githubSource(raw.source),
+      prepared: raw.prepared === null ? null : skillGeneration(raw.prepared),
+      etag: savedString(raw.etag), checkedAt: savedString(raw.checkedAt),
+      retryAt: savedNumber(raw.retryAt), rateLimit: savedNumber(raw.rateLimit), problem: savedString(raw.problem),
+      repositoryId: typeof raw.repositoryId === 'number' ? raw.repositoryId : null,
+    };
+  } catch { throw new Error('The saved GitHub skills source is unreadable. Restore it before changing the source.'); }
+}
+
+function agentJson(path: string): unknown {
+  try {
+    if (statSync(path).size > SKILL_MANIFEST_MAX) return null;
+    return JSON.parse(readFileSync(path, 'utf8')) as unknown;
+  } catch { return null; }
+}
+
+export class GitHubSkills {
+  private readonly path: string;
+  readonly root: string;
+  private stored: Stored = { ...EMPTY };
+  private unreadable = false;
+  private busy = false;
+  private epoch = 0;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private readonly deps: GitHubSkillsDeps) {
+    this.path = join(deps.agents, 'github-skills.json');
+    this.root = skillSourceRoot(deps.claude);
+    try { this.stored = readStored(this.path); }
+    catch { this.unreadable = true; }
+  }
+
+  private readable(): void {
+    if (!this.unreadable) return;
+    this.stored = readStored(this.path);
+    this.unreadable = false;
+  }
+
+  private save(): void {
+    this.readable();
+    writeSecure(this.path, JSON.stringify(this.stored));
+  }
+
+  private activation(): { generation: string | null; appliedAt: string | null; problem: string | null; shadowed: string[] } {
+    const raw = agentJson(join(this.root, 'status.json'));
+    if (!isRecord(raw)) return { generation: null, appliedAt: null, problem: null, shadowed: [] };
+    return {
+      generation: typeof raw.generation === 'string' && SKILL_HASH.test(raw.generation) ? raw.generation : null,
+      appliedAt: typeof raw.appliedAt === 'string' ? raw.appliedAt : null,
+      problem: typeof raw.problem === 'string' ? raw.problem.slice(0, 300) : null,
+      shadowed: Array.isArray(raw.shadowed) ? raw.shadowed.filter((name): name is string => typeof name === 'string').slice(0, 64) : [],
+    };
+  }
+
+  private loaded(activation = this.activation()): SkillGeneration | null {
+    const id = activation.generation;
+    if (id === null) return null;
+    try { return skillGeneration(agentJson(join(skillRelease(this.root, id), 'manifest.json'))); }
+    catch { return null; }
+  }
+
+  view(activation = this.activation(), loaded = this.loaded(activation)): object {
+    const { source, prepared, checkedAt, problem } = this.stored;
+    return {
+      supported: this.deps.sdk(),
+      source: source === null ? null : { repository: source.repository, ref: source.ref, folder: source.folder, hasToken: true },
+      checking: this.busy, checkedAt, problem: this.unreadable ? 'The saved GitHub source is unreadable. Restore its configuration before changing it. Local skills are still available.' : problem,
+      prepared: prepared === null ? null : { generation: prepared.id, source: prepared.source, skillCount: prepared.skills.length },
+      loaded: loaded?.source ?? null, activation,
+      pending: prepared !== null && prepared.id !== activation.generation,
+    };
+  }
+
+  listing(): { rows: ClaudeSkill[]; skillSource: object } {
+    const activation = this.activation();
+    const loaded = this.loaded(activation);
+    return { rows: this.rows(activation, loaded), skillSource: this.view(activation, loaded) };
+  }
+
+  rows(activation = this.activation(), loaded = this.loaded(activation)): ClaudeSkill[] {
+    if (loaded === null) return [];
+    const shadowed = activation.shadowed;
+    return loaded.skills.map((skill) => ({
+      id: `github:${skill.name}`, name: skill.name, title: skill.name, description: skill.description,
+      path: join(skillRelease(this.root, loaded.id), 'skills', skill.name, 'SKILL.md'), editable: false,
+      updatedAt: loaded.createdAt, managed: true, shadowed: shadowed.includes(skill.name),
+    }));
+  }
+
+  read(id: string): ClaudeSkill & { text: string } {
+    const row = this.rows().find((skill) => skill.id === id);
+    if (row === undefined) throw new ApiError('no such skill', 404);
+    if (statSync(row.path).size > 256 * 1024) throw new ApiError('The managed skill changed on disk. Sync it again.', 409);
+    return { ...row, text: readFileSync(row.path, 'utf8') };
+  }
+
+  async configure(raw: unknown): Promise<object> {
+    if (!this.deps.sdk()) throw new ApiError('GitHub skills require the Agent SDK runner. Local skills are unchanged.', 409);
+    if (this.busy) throw new ApiError('A skills sync is already running. Try again when it finishes.', 409);
+    const source = githubSource(raw);
+    this.readable();
+    const loaded = this.loaded();
+    this.epoch += 1;
+    this.stored = { ...this.stored, source, prepared: loaded, etag: null, retryAt: 0, problem: null, repositoryId: null };
+    if (loaded === null) await this.publish(validatedGeneration(null, null), new Map(), this.epoch);
+    else { this.save(); this.offer(); }
+    await this.sync(true);
+    return this.view();
+  }
+
+  async remove(): Promise<object> {
+    this.readable();
+    this.epoch += 1;
+    this.stored = { ...EMPTY };
+    this.save();
+    await this.publish(validatedGeneration(null, null), new Map(), this.epoch);
+    return this.view();
+  }
+
+  private waiting(force: boolean): boolean {
+    if (Date.now() < this.stored.rateLimit) return true;
+    if (force) return false;
+    return Date.now() < this.stored.retryAt || (this.stored.prepared !== null && this.stored.prepared.id !== this.activation().generation);
+  }
+
+  private reader(source: Configuration, known: SkillGeneration['source'], force: boolean): ReturnType<GitHubReader['snapshot']> {
+    return new GitHubReader(source, source.token, this.deps.request).snapshot(this.stored.repositoryId, force ? null : known?.commit ?? null, force ? null : this.stored.etag);
+  }
+
+  private async fetch(source: Configuration, epoch: number, force: boolean): Promise<void> {
+    const previous = this.stored.prepared?.source;
+    const same = previous?.repository === source.repository && previous.ref === source.ref && previous.folder === source.folder;
+    const known = same ? previous : null;
+    const snapshot = await this.reader(source, known, force);
+    if (epoch !== this.epoch) return;
+    if (snapshot !== null) {
+      const generation = validatedGeneration(source, snapshot);
+      this.stored.etag = snapshot.etag;
+      this.stored.repositoryId = snapshot.repositoryId;
+      await this.publish(generation, snapshot.files, epoch);
+      if (epoch !== this.epoch) return;
+    }
+    this.stored.checkedAt = new Date().toISOString();
+    this.stored.problem = null;
+    this.stored.retryAt = Date.now() + 60_000;
+  }
+
+  async sync(force = false): Promise<void> {
+    if (force && !this.deps.sdk()) throw new ApiError('GitHub skills require the Agent SDK runner. Local skills are unchanged.', 409);
+    this.readable();
+    this.offer();
+    const source = this.stored.source;
+    if (source === null || this.busy || !this.deps.sdk() || this.waiting(force)) return;
+    const epoch = this.epoch;
+    this.busy = true;
+    try { await this.fetch(source, epoch, force); }
+    catch (err) {
+      if (epoch !== this.epoch) return;
+      this.failure(err);
+    } finally {
+      this.busy = false;
+      this.save();
+    }
+  }
+
+  private failure(err: unknown): void {
+    this.stored.problem = err instanceof GitHubFailure ? err.message : 'The repository failed skill validation or staging. Keep one folder per skill, safe metadata and regular files. The loaded skills are kept.';
+    this.stored.retryAt = err instanceof GitHubFailure ? err.retryAt : Date.now() + 5 * 60_000;
+    if (err instanceof GitHubFailure && err.rateLimited) this.stored.rateLimit = err.retryAt;
+    this.stored.checkedAt = new Date().toISOString();
+  }
+
+  private offer(): void {
+    const generation = this.stored.prepared;
+    if (generation === null) return;
+    const pending = agentJson(join(this.root, 'pending.json'));
+    if (isRecord(pending) && pending.id === generation.id) return;
+    writeHomeText(join(this.root, 'pending.json'), JSON.stringify(generation), 0o600);
+  }
+
+  private async publish(generation: SkillGeneration, files: Map<string, Buffer>, epoch: number): Promise<void> {
+    const release = skillRelease(this.root, generation.id);
+    const deadline = Date.now() + 120_000;
+    for (const [path, bytes] of files) {
+      if (epoch !== this.epoch) return;
+      if (Date.now() > deadline) throw new Error('Staging skills timed out.');
+      const mode = generation.files.find((file) => file.path === path)?.executable === true ? 0o700 : 0o600;
+      await receiveHomeFile(join(release, 'skills', path), Readable.from(bytes), mode);
+    }
+    if (epoch !== this.epoch) return;
+    writeHomeText(join(release, 'manifest.json'), JSON.stringify(generation), 0o600);
+    this.stored.prepared = generation;
+    this.save();
+    this.offer();
+  }
+
+  watch(): void {
+    if (this.timer !== null) return;
+    const tick = (): void => {
+      this.sync().catch(() => { log.warn('github-skills: could not save sync state'); });
+      this.timer = setTimeout(tick, 60_000 + Math.floor(Math.random() * 5_000));
+      this.timer.unref();
+    };
+    tick();
+  }
+}
+
+let current: GitHubSkills | null = null;
+export function githubSkills(): GitHubSkills {
+  current ??= new GitHubSkills({ agents: agentsDir(), claude: claudeDir(), sdk: () => readSetupState(agentsDir()).runner === 'sdk' });
+  return current;
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/github-validate.ts

@@ -0,0 +1,53 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { isRecord } from '@metro-labs/core/is-record';
+import { SKILL_NAME, skillGeneration, type SkillGeneration, type SkillSource } from '@metro-labs/core/skill-source';
+import { ApiError } from '@metro-labs/http/api-error';
+import type { GitHubSnapshot } from './github-fetch.js';
+
+const FIELDS = new Set(['name', 'description', 'argument-hint', 'disable-model-invocation', 'user-invocable']);
+export const skillDigest = (bytes: string | Uint8Array): string => createHash('sha256').update(bytes).digest('hex');
+
+function validRef(value: unknown): value is string {
+  return typeof value === 'string' && value.length <= 200 && /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(value) && !value.includes('..') && !value.includes('//');
+}
+
+function validFolder(value: unknown): value is string {
+  if (typeof value !== 'string' || value.length > 240) return false;
+  if (value === '') return true;
+  const parts = value.split('/');
+  return parts.length <= 6 && parts.every((part) => /^[A-Za-z0-9._-]{1,80}$/.test(part) && part !== '.' && part !== '..');
+}
+
+export function githubSource(raw: unknown): SkillSource & { token: string } {
+  if (!isRecord(raw) || typeof raw.repository !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(raw.repository)) throw new ApiError('Use a GitHub repository in owner/repository form.', 400);
+  if (!validRef(raw.ref)) throw new ApiError('Use a branch, tag or full commit SHA.', 400);
+  if (!validFolder(raw.folder)) throw new ApiError('Use a relative skills folder, or leave it empty for the repository root.', 400);
+  if (typeof raw.token !== 'string' || !/^github_pat_[A-Za-z0-9_]{20,240}$/.test(raw.token)) throw new ApiError('Use a fine-grained GitHub token with Contents read access to this repository only.', 400);
+  return { repository: raw.repository, ref: raw.ref, folder: raw.folder, token: raw.token };
+}
+
+function passiveMetadata(meta: Record<string, unknown>): void {
+  if (Object.keys(meta).some((key) => !FIELDS.has(key))) throw new Error('Unsupported skill metadata. Only name, description, argument-hint, disable-model-invocation and user-invocable are allowed. Hooks, tool grants, model changes and agents are not imported.');
+  if (['disable-model-invocation', 'user-invocable'].some((key) => key in meta && typeof meta[key] !== 'boolean') || ('argument-hint' in meta && typeof meta['argument-hint'] !== 'string')) throw new Error('Invalid skill metadata types.');
+}
+
+function skillMetadata(name: string, bytes: Buffer): { name: string; description: string } {
+  const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+  if (match === null || /!`|\0/.test(text)) throw new Error('A skill needs YAML frontmatter. Shell substitutions are not supported.');
+  const meta: unknown = Bun.YAML.parse(match[1] ?? '');
+  if (!isRecord(meta) || meta.name !== name || !SKILL_NAME.test(name) || typeof meta.description !== 'string' || meta.description.trim() === '' || meta.description.length > 1024) throw new Error('A skill needs a name matching its folder and a description of up to 1024 characters.');
+  passiveMetadata(meta);
+  return { name, description: meta.description };
+}
+
+export function validatedGeneration(source: SkillSource | null, snapshot: GitHubSnapshot | null): SkillGeneration {
+  const files = snapshot?.files ?? new Map<string, Buffer>();
+  const skills = [...files].filter(([path]) => path.endsWith('/SKILL.md')).map(([path, bytes]) => skillMetadata(path.split('/')[0] ?? '', bytes));
+  const manifest = {
+    source: source === null || snapshot === null ? null : { repository: source.repository, ref: source.ref, folder: source.folder, repositoryId: snapshot.repositoryId, commit: snapshot.commit },
+    skills,
+    files: [...files].map(([path, bytes]) => ({ path, size: bytes.byteLength, sha256: skillDigest(bytes), ...(snapshot?.executables?.includes(path) === true ? { executable: true } : {}) })),
+  };
+  return skillGeneration({ ...manifest, id: skillDigest(randomUUID()), createdAt: new Date().toISOString() });
+}