@qvac/harness 0.0.0 → 0.1.1

package/dist-lib/lib/tools/read-files.js

@@ -0,0 +1,153 @@
+import { readLines } from "./fs/read.js";
+import { isDriveReadTruncated } from "./fs/remote.js";
+import { canonicalDenyRoots, defaultRealpath, resolveKey } from "./fs/scope.js";
+export const DEFAULT_READ_CHARS = 8192;
+export const MAX_READ_CHARS = 65_536;
+function lineIndex(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1)
+        return null;
+    return n;
+}
+function fileRequests(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return null;
+    const files = [];
+    for (const entry of raw) {
+        const record = entry;
+        if (typeof record?.path !== 'string' || !record.path.trim())
+            return null;
+        const startLine = lineIndex(record.startLine);
+        const endLine = lineIndex(record.endLine);
+        if (startLine === null || endLine === null)
+            return null;
+        files.push({
+            path: record.path,
+            ...(startLine !== undefined ? { startLine } : {}),
+            ...(endLine !== undefined ? { endLine } : {})
+        });
+    }
+    return files;
+}
+async function slice(drive, key, request, maxChars) {
+    const first = request.startLine ?? 1;
+    const last = request.endLine ?? Infinity;
+    const kept = [];
+    let length = 0;
+    let index = 0;
+    let capped = false;
+    try {
+        for await (const line of readLines(drive, key)) {
+            if (++index < first)
+                continue;
+            if (index > last)
+                break;
+            kept.push(line);
+            length += line.length + (kept.length > 1 ? 1 : 0);
+            if (length > maxChars)
+                break;
+        }
+    }
+    catch (err) {
+        if (!isDriveReadTruncated(err))
+            throw err;
+        capped = true;
+    }
+    const text = kept.join('\n');
+    return text.length > maxChars || capped
+        ? { content: text.slice(0, maxChars), truncated: true }
+        : { content: text };
+}
+export function createReadFilesTool({ realpath = defaultRealpath, deniedRoots } = {}) {
+    return {
+        name: 'read_files',
+        toolset: 'files',
+        description: 'Read the contents of one or more files inside the granted directories. ' +
+            'Optionally slice by 1-indexed line range. Failures are reported per file.',
+        parameters: {
+            type: 'object',
+            properties: {
+                files: {
+                    type: 'array',
+                    description: 'Files to read',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'File path' },
+                            startLine: { type: 'number', description: 'Optional 1-indexed first line' },
+                            endLine: { type: 'number', description: 'Optional 1-indexed last line (inclusive)' }
+                        },
+                        required: ['path']
+                    }
+                },
+                maxChars: {
+                    type: 'number',
+                    description: `Optional per-file cap in characters (default ${DEFAULT_READ_CHARS}, max ${MAX_READ_CHARS})`
+                }
+            },
+            required: ['files']
+        },
+        effect: () => 'read',
+        autoApprove: true,
+        rootsRequired: true,
+        validate(rawArgs) {
+            if (!fileRequests(rawArgs.files)) {
+                return 'files must be a non-empty array of { path } with optional positive integer startLine/endLine';
+            }
+            const maxChars = rawArgs.maxChars;
+            if (maxChars !== undefined && maxChars !== null) {
+                const n = Number(maxChars);
+                if (!Number.isInteger(n) || n <= 0 || n > MAX_READ_CHARS) {
+                    return `maxChars must be a positive integer ≤ ${MAX_READ_CHARS}`;
+                }
+            }
+            return null;
+        },
+        resource(args) {
+            const files = fileRequests(args.files);
+            if (!files)
+                return null;
+            const label = files
+                .map((f) => f.path)
+                .slice(0, 3)
+                .join(', ');
+            return {
+                kind: 'file',
+                label: files.length > 3 ? `${label} (+${files.length - 3} more)` : label
+            };
+        },
+        async execute(rawArgs, ctx) {
+            const roots = ctx?.fsRoots ?? [];
+            const requests = fileRequests(rawArgs.files);
+            if (!requests)
+                return { error: 'files must be a non-empty array of { path }' };
+            const maxChars = rawArgs.maxChars ? Number(rawArgs.maxChars) : DEFAULT_READ_CHARS;
+            const files = [];
+            const failed = [];
+            const deny = await canonicalDenyRoots(deniedRoots, realpath);
+            for (const request of requests) {
+                const resolved = await resolveKey(request.path, roots, realpath, deny);
+                if ('error' in resolved) {
+                    failed.push({ path: request.path, error: resolved.error });
+                    continue;
+                }
+                try {
+                    if ((await resolved.root.drive.entry(resolved.key)) === null) {
+                        failed.push({ path: request.path, error: `no such file: ${request.path}` });
+                        continue;
+                    }
+                    files.push({
+                        path: request.path,
+                        ...(await slice(resolved.root.drive, resolved.key, request, maxChars))
+                    });
+                }
+                catch (err) {
+                    failed.push({ path: request.path, error: err.message });
+                }
+            }
+            return { files, ...(failed.length ? { failed } : {}) };
+        }
+    };
+}

package/dist-lib/lib/tools/skill.d.ts

@@ -0,0 +1,10 @@
+import type { ToolDefinition } from '../capabilities/completion.ts';
+import { type CredentialStoreFn } from './skills/auth-resolver.ts';
+export type ReadSkillFn = (name: string, file: string) => Promise<string> | string;
+export interface SkillToolOptions {
+    skillsDir?: string;
+    overlayDir?: string | null;
+    read?: ReadSkillFn;
+    credentialStore?: CredentialStoreFn;
+}
+export declare function createSkillTool({ skillsDir, overlayDir, read, credentialStore }?: SkillToolOptions): ToolDefinition;

package/dist-lib/lib/tools/skill.js

@@ -0,0 +1,123 @@
+import path from 'path';
+import b4a from 'b4a';
+import Localdrive from 'localdrive';
+import { OBSIDIAN_VAULT_MODE_NOTE } from "./exec/obsidian/guidance.js";
+import { unquoteArg } from "./model-args.js";
+import { credentialRecord } from "./skills/auth-resolver.js";
+import { resolveSkillsOverlayDir } from "./skills/overlay-dir.js";
+import { parseSkillFrontMatter } from "./skills/frontmatter-parser.js";
+import { parseToolGrant } from "./skills/tool-grants.js";
+import { shellEscapeArg } from "./exec/shell-argv.js";
+import { isObsidianVaultPath, OBSIDIAN_SKILL_NAME, OBSIDIAN_VAULT_PATH_CREDENTIAL_KEY } from "./skills/obsidian-readiness.js";
+const MAIN_FILE = 'SKILL.md';
+function resolveSkillDir(root, name) {
+    if (!root)
+        return null;
+    return path.resolve(root, name);
+}
+function toolNote(tools) {
+    if (!tools?.length)
+        return null;
+    const grants = [];
+    for (const entry of tools) {
+        const { name } = parseToolGrant(entry);
+        if (!grants.includes(name))
+            grants.push(name);
+    }
+    return [
+        `You can now call: ${grants.join(', ')}.`,
+        'Do this work yourself with those tools in this turn — never tell the user to install ' +
+            'anything, open another app, or run code themselves.'
+    ].join(' ');
+}
+async function listSkillFiles(drives, name) {
+    const files = new Set();
+    for (const drive of drives) {
+        if (!drive)
+            continue;
+        try {
+            for await (const entry of drive.list(`/${name}`)) {
+                const rel = String(entry.key).slice(name.length + 2);
+                if (rel && rel !== 'SKILL.md')
+                    files.add(rel);
+            }
+        }
+        catch {
+        }
+    }
+    return [...files].sort();
+}
+async function vaultModeNote(name, credentialStore, ctx) {
+    if (name !== OBSIDIAN_SKILL_NAME || !credentialStore)
+        return null;
+    const record = credentialRecord(await credentialStore(OBSIDIAN_VAULT_PATH_CREDENTIAL_KEY, { ...ctx, skills: [name] }));
+    const token = record?.token?.trim();
+    if (!token || !isObsidianVaultPath(token))
+        return null;
+    return OBSIDIAN_VAULT_MODE_NOTE;
+}
+export function createSkillTool({ skillsDir, overlayDir = resolveSkillsOverlayDir(), read, credentialStore } = {}) {
+    const baseDrive = skillsDir ? new Localdrive(skillsDir) : null;
+    const overlayDrive = overlayDir ? new Localdrive(overlayDir) : null;
+    async function resolveSkill(name, file) {
+        if (read)
+            return { raw: await read(name, file), root: skillsDir };
+        for (const [drive, root] of [
+            [overlayDrive, overlayDir],
+            [baseDrive, skillsDir]
+        ]) {
+            const buf = drive ? await drive.get(`/${name}/${file}`) : null;
+            if (buf)
+                return { raw: b4a.toString(buf, 'utf8'), root: root ?? undefined };
+        }
+        throw new Error(`ENOENT: ${name}/${file}`);
+    }
+    return {
+        name: 'skill',
+        toolset: null,
+        description: 'Load the instructions for a named skill. Call this FIRST, before any other tool, whenever a listed skill covers the capability you are about to use. When loaded instructions point to another file in the skill, call this again with `name` and `file` to load it before doing the work it covers.',
+        parameters: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: "The skill's name" },
+                file: {
+                    type: 'string',
+                    description: "Path of a file inside the skill to load, exactly as the skill's instructions name it (e.g. 'references/edit.md'). Omit to load the main instructions."
+                }
+            },
+            required: ['name']
+        },
+        effect: () => 'read',
+        autoApprove: true,
+        async execute(args, ctx) {
+            const name = unquoteArg(args.name ?? args.skill_name ?? args.skill);
+            const fileArg = args.file ?? args.path ?? args.filename;
+            const file = fileArg === undefined || fileArg === null ? MAIN_FILE : unquoteArg(fileArg);
+            if (file.startsWith('/') || file.includes('\\') || file.split('/').includes('..')) {
+                return { error: `file not found in skill ${name}: ${file}` };
+            }
+            try {
+                const { raw, root } = await resolveSkill(name, file === '' ? MAIN_FILE : file);
+                const { body, meta } = parseSkillFrontMatter(raw);
+                const dir = resolveSkillDir(root, name);
+                const content = dir ? body.replaceAll('{{SKILL_DIR}}', shellEscapeArg(dir)) : body;
+                const notes = [
+                    toolNote(meta.tools),
+                    await vaultModeNote(name, credentialStore, ctx)
+                ].filter(Boolean);
+                return {
+                    name,
+                    file: file === MAIN_FILE || file === '' ? undefined : file,
+                    content: notes.length ? [content.trim(), ...notes].join('\n\n') : content
+                };
+            }
+            catch {
+                if (file === MAIN_FILE)
+                    return { error: `skill not found: ${name}` };
+                const available = await listSkillFiles([overlayDrive, baseDrive], name);
+                const listing = available.length ? ` — files this skill has: ${available.join(', ')}` : '';
+                return { error: `file not found in skill ${name}: ${file}${listing}` };
+            }
+        }
+    };
+}

package/dist-lib/lib/tools/skills/auth-resolver.d.ts

@@ -0,0 +1,43 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { ToolExecuteContext } from '../../capabilities/completion.ts';
+import { type ParseResult } from '../http-request/utils.ts';
+export interface HttpRequestAuth {
+    type: 'bearer';
+    tokenCredentialKey: string;
+}
+export interface CredentialRecord {
+    readonly token: string;
+    readonly expiresAt?: number;
+}
+export type CredentialStoreValue = CredentialRecord | string | null;
+export type CredentialStoreFn = (key: string, ctx?: ToolExecuteContext) => Promise<CredentialStoreValue> | CredentialStoreValue;
+export declare function credentialRecord(value: CredentialStoreValue): CredentialRecord | null;
+export declare function isCredentialExpired(record: CredentialRecord, now?: number): boolean;
+export type CredentialAllowList = Record<string, string | string[]>;
+export declare function urlAllowed(url: URL, patterns: readonly string[]): boolean;
+export declare function isCredentialUrlAllowed(target: string, patterns: readonly string[]): boolean;
+export type CredentialAllowListFn = (ctx?: ToolExecuteContext) => CredentialAllowList;
+export type AuthOutcome = {
+    readonly token: string;
+} | {
+    readonly error: string;
+};
+export declare function parseAuth(v: unknown): ParseResult<HttpRequestAuth>;
+export declare function resolveAuth(auth: HttpRequestAuth, url: URL, credentialStore: CredentialStoreFn | undefined, credentialAllowList: CredentialAllowList | undefined, ctx: ToolExecuteContext | undefined): Promise<AuthOutcome>;
+export declare function resolveAutoAuth(url: URL, credentialStore: CredentialStoreFn | undefined, credentialAllowList: CredentialAllowList | undefined, ctx: ToolExecuteContext | undefined): Promise<{
+    token: string;
+    key: string;
+} | {
+    error: string;
+} | null>;
+export type BearerOutcome = {
+    readonly header: string | null;
+    readonly credentialKey?: string;
+} | {
+    readonly error: string;
+};
+export declare function resolveBearerHeader(auth: HttpRequestAuth | undefined, url: URL, credentialStore: CredentialStoreFn | undefined, credentialAllowList: CredentialAllowList | undefined, ctx: ToolExecuteContext | undefined, signal: BareAbortSignal): Promise<BearerOutcome>;
+export declare function resolveRedirectBearerHeader(auth: HttpRequestAuth | undefined, url: URL, credentialStore: CredentialStoreFn | undefined, credentialAllowList: CredentialAllowList | undefined, ctx: ToolExecuteContext | undefined, signal: BareAbortSignal): Promise<{
+    readonly header: string | null;
+    readonly credentialKey?: string;
+}>;

package/dist-lib/lib/tools/skills/auth-resolver.js

@@ -0,0 +1,121 @@
+import { raceAbort } from "../../helpers/race-abort.js";
+import { parseObjectArg } from "../http-request/utils.js";
+export function credentialRecord(value) {
+    if (typeof value === 'string')
+        return value ? { token: value } : null;
+    return value?.token ? value : null;
+}
+export function isCredentialExpired(record, now = Date.now()) {
+    return typeof record.expiresAt === 'number' && now + 60_000 >= record.expiresAt;
+}
+function pathAllowed(target, prefix) {
+    if (target === prefix)
+        return true;
+    return target.startsWith(prefix.endsWith('/') ? prefix : `${prefix}/`);
+}
+function matchesPattern(url, pattern) {
+    const glob = pattern.endsWith('*');
+    const raw = glob ? pattern.slice(0, -1) : pattern;
+    let base;
+    try {
+        base = new URL(raw);
+    }
+    catch {
+        return url.href.startsWith(raw);
+    }
+    if (url.protocol !== base.protocol || url.host !== base.host)
+        return false;
+    return glob ? url.pathname.startsWith(base.pathname) : pathAllowed(url.pathname, base.pathname);
+}
+export function urlAllowed(url, patterns) {
+    return patterns.some((p) => matchesPattern(url, p));
+}
+export function isCredentialUrlAllowed(target, patterns) {
+    try {
+        return urlAllowed(new URL(target), patterns);
+    }
+    catch {
+        return false;
+    }
+}
+export function parseAuth(v) {
+    const parsed = parseObjectArg(v, 'auth');
+    if (!parsed.ok)
+        return parsed;
+    if (!parsed.value)
+        return { ok: true, value: undefined };
+    const { type, tokenCredentialKey } = parsed.value;
+    if (type !== undefined && type !== 'bearer') {
+        return { ok: false, error: `unsupported auth type: ${String(type)}` };
+    }
+    const key = typeof tokenCredentialKey === 'string' && tokenCredentialKey.length > 0
+        ? tokenCredentialKey
+        : null;
+    if (key === null) {
+        const blank = tokenCredentialKey === undefined || tokenCredentialKey === null || tokenCredentialKey === '';
+        if (!blank) {
+            return { ok: false, error: 'auth.tokenCredentialKey must be a non-empty string' };
+        }
+        return { ok: true, value: undefined };
+    }
+    return { ok: true, value: { type: 'bearer', tokenCredentialKey: key } };
+}
+export async function resolveAuth(auth, url, credentialStore, credentialAllowList, ctx) {
+    const key = auth.tokenCredentialKey;
+    if (!credentialStore)
+        return { error: 'credentials not configured' };
+    const entry = credentialAllowList?.[key];
+    if (!entry) {
+        return {
+            error: `credential ${key} is not available here — load the skill that declares it first`
+        };
+    }
+    const patterns = Array.isArray(entry) ? entry : [entry];
+    if (!urlAllowed(url, patterns)) {
+        return { error: `credential ${key} is not allowed for URL ${url.href}` };
+    }
+    const record = credentialRecord(await credentialStore(key, ctx));
+    if (!record)
+        return { error: `unknown credential: ${key}` };
+    return { token: record.token };
+}
+export async function resolveAutoAuth(url, credentialStore, credentialAllowList, ctx) {
+    if (!credentialStore || !credentialAllowList)
+        return null;
+    let selected = null;
+    for (const [key, entry] of Object.entries(credentialAllowList)) {
+        const patterns = Array.isArray(entry) ? entry : [entry];
+        if (!urlAllowed(url, patterns))
+            continue;
+        const record = credentialRecord(await credentialStore(key, ctx));
+        if (!record)
+            continue;
+        if (selected) {
+            return { error: 'multiple credentials match this URL; set auth.tokenCredentialKey' };
+        }
+        selected = { token: record.token, key };
+    }
+    return selected;
+}
+export async function resolveBearerHeader(auth, url, credentialStore, credentialAllowList, ctx, signal) {
+    if (auth) {
+        const resolved = await raceAbort(resolveAuth(auth, url, credentialStore, credentialAllowList, ctx), signal);
+        if ('error' in resolved)
+            return { error: resolved.error };
+        return { header: `Bearer ${resolved.token}`, credentialKey: auth.tokenCredentialKey };
+    }
+    const resolved = await raceAbort(resolveAutoAuth(url, credentialStore, credentialAllowList, ctx), signal);
+    if (resolved && 'error' in resolved)
+        return resolved;
+    return resolved
+        ? { header: `Bearer ${resolved.token}`, credentialKey: resolved.key }
+        : { header: null };
+}
+export async function resolveRedirectBearerHeader(auth, url, credentialStore, credentialAllowList, ctx, signal) {
+    if (!auth)
+        return { header: null };
+    const resolved = await raceAbort(resolveAuth(auth, url, credentialStore, credentialAllowList, ctx), signal);
+    return 'error' in resolved
+        ? { header: null }
+        : { header: `Bearer ${resolved.token}`, credentialKey: auth.tokenCredentialKey };
+}

package/dist-lib/lib/tools/skills/bin-check.d.ts

@@ -0,0 +1,9 @@
+import type { SkillRequires } from './manifest.ts';
+export type BinVersionState = 'ok' | 'too-old' | 'unknown';
+export declare function binOnPath(bin: string, platform?: string): boolean;
+export declare function missingBins(bins: readonly string[], platform?: string, probe?: (bin: string, platform?: string) => boolean): string[];
+export declare function probeBinVersions(requires: SkillRequires | undefined, opts: {
+    platform?: string;
+    run: (command: string) => Promise<string | null>;
+    binPresent?: (bin: string) => boolean | Promise<boolean>;
+}): Promise<Map<string, BinVersionState>>;

package/dist-lib/lib/tools/skills/bin-check.js

@@ -0,0 +1,56 @@
+import fs from 'fs';
+import path from 'path';
+import process from 'process';
+import { withHomebrewPath } from "../../helpers/spawn-path.js";
+const SAFE_BIN_NAME = /^[A-Za-z0-9._-]+$/;
+function envPath() {
+    return process.env.PATH ?? process.env.Path ?? '';
+}
+function existsFile(p) {
+    try {
+        return fs.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+export function binOnPath(bin, platform) {
+    if (!SAFE_BIN_NAME.test(bin))
+        return false;
+    const searchPath = withHomebrewPath(envPath(), platform ?? process.platform) ?? '';
+    const dirs = searchPath.split(path.delimiter).filter((d) => d.length > 0);
+    const names = platform === 'win32' ? [bin, `${bin}.exe`, `${bin}.cmd`, `${bin}.bat`] : [bin];
+    return dirs.some((dir) => names.some((name) => existsFile(path.join(dir, name))));
+}
+export function missingBins(bins, platform, probe = binOnPath) {
+    return bins.filter((bin) => !probe(bin, platform));
+}
+function parseVersion(text) {
+    const m = text.match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : null;
+}
+function isBelow(found, min) {
+    for (let i = 0; i < Math.max(found.length, min.length); i++) {
+        const f = found[i] ?? 0;
+        const m = min[i] ?? 0;
+        if (f !== m)
+            return f < m;
+    }
+    return false;
+}
+export async function probeBinVersions(requires, opts) {
+    const states = new Map();
+    const mins = requires?.binMinVersions;
+    if (!mins)
+        return states;
+    const binPresent = opts.binPresent ?? ((bin) => binOnPath(bin, opts.platform));
+    for (const [bin, spec] of Object.entries(mins)) {
+        if (!spec.command || !(await binPresent(bin)))
+            continue;
+        const output = await opts.run(spec.command);
+        const found = output === null ? null : parseVersion(output);
+        const min = parseVersion(spec.min);
+        states.set(bin, found && min ? (isBelow(found, min) ? 'too-old' : 'ok') : 'unknown');
+    }
+    return states;
+}

package/dist-lib/lib/tools/skills/bundled-dir.d.ts

@@ -0,0 +1,2 @@
+export declare function ensureBundledSkillsDir(): Promise<string>;
+export declare function randomSuffix(): string;

package/dist-lib/lib/tools/skills/bundled-dir.js

@@ -0,0 +1,117 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import process from 'process';
+import { userTmpPath } from "../../tmp-path.js";
+import { hashBundledSkills } from "./bundled-hash.js";
+import { SKILLS as BUNDLED_SKILLS } from '@qvac/skills/bundled';
+import { SKILLS_HASH as BUNDLED_SKILLS_HASH } from '@qvac/skills/hash';
+let inflight = null;
+export function ensureBundledSkillsDir() {
+    inflight ??= materialize().finally(() => {
+        inflight = null;
+    });
+    return inflight;
+}
+async function materialize() {
+    const dir = userTmpPath('qvac-harness-skills-' + BUNDLED_SKILLS_HASH);
+    if (await validTree(dir))
+        return dir;
+    const staging = `${dir}-staging-${process.pid}-${randomSuffix()}`;
+    await fs.promises.mkdir(staging, { recursive: true });
+    if (os.platform() !== 'win32')
+        await fs.promises.chmod(staging, 0o700);
+    try {
+        await writeTree(staging);
+        if (!(await validTree(staging))) {
+            throw new Error(`bundled skills staging dir ${staging} failed validation`);
+        }
+        if (await tryRename(staging, dir))
+            return dir;
+        if (await validTree(dir))
+            return dir;
+        const trash = `${dir}.trash-${process.pid}-${randomSuffix()}`;
+        try {
+            await fs.promises.rename(dir, trash);
+        }
+        catch (err) {
+            if (await validTree(dir))
+                return dir;
+            throw occupiedError(dir, err);
+        }
+        void fs.promises.rm(trash, { recursive: true, force: true });
+        if (await tryRename(staging, dir))
+            return dir;
+        if (await validTree(dir))
+            return dir;
+        throw tamperError(dir);
+    }
+    finally {
+        await fs.promises.rm(staging, { recursive: true, force: true });
+    }
+}
+function tamperError(dir) {
+    return new Error(`bundled skills dir ${dir} failed validation after a rewrite — ` +
+        'another process is tampering with it; remove it and restart');
+}
+function occupiedError(dir, cause) {
+    const why = cause instanceof Error ? ` (${cause.message})` : '';
+    return new Error(`bundled skills dir ${dir} could not be read or replaced${why} — remove it and restart`);
+}
+export function randomSuffix() {
+    return Math.random().toString(36).slice(2, 10);
+}
+async function tryRename(from, to) {
+    try {
+        await fs.promises.rename(from, to);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeTree(dir) {
+    for (const [relPath, content] of Object.entries(BUNDLED_SKILLS)) {
+        const target = path.join(dir, relPath);
+        await fs.promises.mkdir(path.dirname(target), { recursive: true });
+        await fs.promises.writeFile(target, content);
+    }
+}
+async function validTree(dir) {
+    try {
+        if (os.platform() !== 'win32') {
+            const stat = await fs.promises.lstat(dir);
+            if (!stat.isDirectory() || (stat.mode & 0o077) !== 0)
+                return false;
+        }
+        const files = await collect(dir, '');
+        if (files === null)
+            return false;
+        return hashBundledSkills(files) === BUNDLED_SKILLS_HASH;
+    }
+    catch {
+        return false;
+    }
+}
+async function collect(dir, prefix) {
+    const files = [];
+    for (const entry of await fs.promises.readdir(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            const nested = await collect(path.join(dir, entry.name), rel);
+            if (nested === null)
+                return null;
+            files.push(...nested);
+        }
+        else if (entry.isFile()) {
+            files.push({
+                path: rel,
+                content: await fs.promises.readFile(path.join(dir, entry.name), 'utf8')
+            });
+        }
+        else {
+            return null;
+        }
+    }
+    return files;
+}

package/dist-lib/lib/tools/skills/bundled-hash.d.ts

@@ -0,0 +1,4 @@
+export declare function hashBundledSkills(files: ReadonlyArray<{
+    path: string;
+    content: string;
+}>): string;

package/dist-lib/lib/tools/skills/bundled-hash.js

@@ -0,0 +1,12 @@
+import crypto from 'crypto';
+export function hashBundledSkills(files) {
+    const hash = crypto.createHash('sha256');
+    const sorted = [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    for (const file of sorted) {
+        hash.update(file.path);
+        hash.update('\0');
+        hash.update(file.content);
+        hash.update('\0');
+    }
+    return hash.digest('hex').slice(0, 16);
+}