vouchington-tooling 0.1.9 → 0.3.0

package/dist/index.mjs

@@ -1,5 +1,8 @@
 /* eslint-disable max-lines -- package entry point enumerates the supported public API. */
+export { linkSkill, readSkillManifest } from './skill-discovery/index.mjs';
 export { codexChildren, codexIdentity, computeTranscriptFacts, formatTranscriptFacts, formatUnavailable, resolveTranscriptFile, runRetrospectiveTranscript, } from './retrospective-transcript/index.mjs';
+export { runRetrospectiveFacts } from './retrospective-facts/index.mjs';
+export { appendJournal, assertSessionId, cleanupSnapshotPartitions, partitionSnapshot, probeBlackboard, readJournal, resolveBlackboardConnection, } from './agent-blackboard/index.mjs';
 export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from './session-friction/index.mjs';
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mjs';
 export { extractAlterTableAddColumnLocations, extractCreateIndexMetadata, extractCreateTableMetadata, extractDefaultFunction, extractDropIndexMetadata, extractFuncCallArgColumnNames, extractMigrationConstraintMetadata, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from './sql-ast/index.mjs';

package/dist/retrospective-facts/exec.d.mts

@@ -0,0 +1,3 @@
+import type { CommandExecutor, CommandResult } from './shared.mts';
+export declare const shell: CommandExecutor;
+export declare function rawBlock(command: string, args: string[], result: CommandResult): string;

package/dist/retrospective-facts/exec.mjs

@@ -0,0 +1,19 @@
+import { spawn } from 'node:child_process';
+export const shell = (command, args) => new Promise((resolve) => {
+    const child = spawn(command, args);
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (data) => {
+        stdout += data;
+    });
+    child.stderr.on('data', (data) => {
+        stderr += data;
+    });
+    child.on('close', (exitCode) => resolve({ ok: exitCode === 0, stdout, stderr, exitCode }));
+    child.on('error', (error) => resolve({ ok: false, stdout, stderr: error.message, exitCode: null }));
+});
+export function rawBlock(command, args, result) {
+    return `$ ${command} ${args.join(' ')}\n${result.stdout}${result.stderr ? `${result.stdout ? '\n' : ''}stderr:\n${result.stderr}` : ''}\n\n`;
+}

package/dist/retrospective-facts/foreign.d.mts

@@ -0,0 +1,2 @@
+import { type CommandExecutor, type RetrospectiveFactsOptions } from './shared.mts';
+export declare function foreignFacts(options: RetrospectiveFactsOptions, execute: CommandExecutor): Promise<string>;

package/dist/retrospective-facts/foreign.mjs

@@ -0,0 +1,36 @@
+import { rawBlock } from './exec.mjs';
+import { apiFiles, count, dirs, format, objectField, readJson, stringField } from './format.mjs';
+import { PR_JSON_FIELDS } from './shared.mjs';
+export async function foreignFacts(options, execute) {
+    const args = ['pr', 'view', options.pr, '--repo', options.repo, '--json', PR_JSON_FIELDS];
+    const result = await execute('gh', args);
+    const data = result.ok ? readJson(result.stdout) : undefined;
+    const state = stringField(data, 'state', result.ok ? 'unavailable' : 'gh failed');
+    const base = stringField(data, 'baseRefName');
+    const merged = state === 'MERGED'
+        ? base === 'main'
+            ? 'yes (GitHub reports PR MERGED into main)'
+            : base === 'unavailable'
+                ? 'unavailable'
+                : `no (GitHub reports PR MERGED into ${base})`
+        : state === 'OPEN' || state === 'CLOSED'
+            ? `no (GitHub reports PR ${state})`
+            : 'unavailable';
+    return format({
+        fetch: 'not run (scoped GitHub repository)',
+        fetchStatus: 'not run',
+        fetchNote: 'scoped GitHub state is authoritative',
+        branch: stringField(data, 'headRefName'),
+        pr: stringField(data, 'number'),
+        state,
+        mergedAt: stringField(data, 'mergedAt'),
+        mergeCommit: objectField(data, 'mergeCommit', 'oid'),
+        merged,
+        commits: 'unavailable',
+        prCommits: count(data, 'commits'),
+        files: apiFiles(data),
+        dirs: dirs(data),
+        changeSource: 'api',
+        scoped: `${options.repo}#${options.pr}`,
+    }, options.raw ? rawBlock('gh', args, result) : '');
+}

package/dist/retrospective-facts/format.d.mts

@@ -0,0 +1,10 @@
+export declare function format(f: Record<string, string | undefined> & {
+    changeSource?: 'api' | 'local';
+}, raw: string): string;
+export declare function readJson(value: string): Record<string, unknown> | undefined;
+export declare function stringField(value: Record<string, unknown> | undefined, key: string, fallback?: string): string;
+export declare function objectField(value: Record<string, unknown> | undefined, key: string, child: string): string | undefined;
+export declare function count(value: Record<string, unknown> | undefined, key: string): string;
+export declare function topDirs(files: string): string;
+export declare function dirs(value: Record<string, unknown> | undefined): string;
+export declare function apiFiles(value: Record<string, unknown> | undefined): string;

package/dist/retrospective-facts/format.mjs

@@ -0,0 +1,64 @@
+export function format(f, raw) {
+    const scoped = f.scoped ? `n/a (scoped to ${f.scoped})` : undefined;
+    const fileSource = f.changeSource === 'api' ? 'GitHub API' : 'origin/main';
+    return `=== Retrospective Facts ===\nFetch: ${f.fetch}\nFetch status: ${f.fetchStatus}\nFetch note: ${f.fetchNote}\nBranch: ${f.branch}\nPR: ${f.pr ?? 'unavailable'}\nPR state: ${f.state}\nPR merged at: ${f.mergedAt ?? 'unavailable'}\nPR merge commit: ${f.mergeCommit ?? 'unavailable'}\nMerged to main: ${f.merged}\nCommits ahead of origin/main: ${f.commits ?? 'unavailable'}\nPR commits: ${f.prCommits ?? 'unavailable'}\nRemote updates for origin/${f.branch}: ${f.remote ?? scoped ?? 'unavailable'}\nPush-like updates for origin/${f.branch}: ${f.pushes ?? scoped ?? 'unavailable'}\nFiles changed from ${fileSource}: ${f.files}\nTop-level dirs changed from ${fileSource}: ${f.dirs}\nWorking tree changes: ${scoped ?? f.working ?? 'unavailable'}\n${raw}`;
+}
+export function readJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function stringField(value, key, fallback = 'unavailable') {
+    const field = value?.[key];
+    return typeof field === 'string' || typeof field === 'number' ? String(field) : fallback;
+}
+export function objectField(value, key, child) {
+    const field = value?.[key];
+    return field && typeof field === 'object'
+        ? stringField(field, child)
+        : undefined;
+}
+export function count(value, key) {
+    const length = listLength(value, key);
+    if (length === undefined)
+        return 'unavailable';
+    return length >= 100
+        ? "100+ (gh's commits list caps at 100; actual count may be higher)"
+        : String(length);
+}
+function listLength(value, key) {
+    return Array.isArray(value?.[key]) ? value[key].length : undefined;
+}
+export function topDirs(files) {
+    const dirs = [
+        ...new Set(files
+            .split('\n')
+            .filter(Boolean)
+            .map((file) => (file.includes('/') ? file.split('/')[0] : 'root'))),
+    ];
+    return dirs.length ? dirs.sort().join(',') : 'none';
+}
+export function dirs(value) {
+    const files = value?.files;
+    if (!Array.isArray(files))
+        return 'unavailable';
+    const result = topDirs(files
+        .map((file) => typeof file === 'object' && file
+        ? stringField(file, 'path', '')
+        : '')
+        .join('\n'));
+    const total = stringField(value, 'changedFiles');
+    return total !== 'unavailable' && Number(total) > files.length
+        ? `${result} (partial: gh returned ${files.length} of ${total} changed files)`
+        : result;
+}
+export function apiFiles(value) {
+    const total = stringField(value, 'changedFiles');
+    const listed = listLength(value, 'files');
+    return total !== 'unavailable' && listed !== undefined && Number(total) !== listed
+        ? `${total} (partial: gh returned ${listed} of ${total} changed files)`
+        : total;
+}

package/dist/retrospective-facts/index.d.mts

@@ -0,0 +1,3 @@
+import type { RetrospectiveFactsOptions } from './shared.mts';
+export type { CommandExecutor, CommandResult, RetrospectiveFactsOptions } from './shared.mts';
+export declare function runRetrospectiveFacts(options: RetrospectiveFactsOptions): Promise<string>;

package/dist/retrospective-facts/index.mjs

@@ -0,0 +1,26 @@
+import { shell } from './exec.mjs';
+import { foreignFacts } from './foreign.mjs';
+import { localFacts } from './local.mjs';
+export async function runRetrospectiveFacts(options) {
+    validate(options);
+    const execute = options.execute ?? shell;
+    return options.repo ? foreignFacts(options, execute) : localFacts(options, execute);
+}
+function validate(options) {
+    if (options.pr !== undefined && !/^\d+$/.test(options.pr))
+        throw new Error('--pr requires a number');
+    if (options.branch !== undefined && (!options.branch || options.branch.startsWith('-')))
+        throw new Error('--branch requires a name');
+    if (options.repo !== undefined && !/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(options.repo))
+        throw new Error('--repo requires an owner/name value');
+    if (options.pr && options.noPr)
+        throw new Error('--pr and --no-pr are mutually exclusive');
+    if (options.repo && options.branch)
+        throw new Error('--branch cannot be combined with --repo');
+    if (options.repo && options.noPr)
+        throw new Error('--no-pr cannot be combined with --repo');
+    if (options.repo && !options.pr)
+        throw new Error('--repo requires --pr (a foreign repo has no current PR for this local branch)');
+    if (!options.pr && !options.branch && !options.noPr)
+        throw new Error('pass --pr <number>, --branch <name>, or --no-pr');
+}

package/dist/retrospective-facts/local.d.mts

@@ -0,0 +1,2 @@
+import { type CommandExecutor, type RetrospectiveFactsOptions } from './shared.mts';
+export declare function localFacts(options: RetrospectiveFactsOptions, execute: CommandExecutor): Promise<string>;

package/dist/retrospective-facts/local.mjs

@@ -0,0 +1,144 @@
+import { rawBlock } from './exec.mjs';
+import { apiFiles, count, dirs, format, objectField, readJson, stringField, topDirs, } from './format.mjs';
+import { PR_JSON_FIELDS, } from './shared.mjs';
+export async function localFacts(options, execute) {
+    const calls = [];
+    const run = async (command, args) => {
+        const result = await execute(command, args);
+        calls.push({ command, args, result });
+        return result;
+    };
+    const mainSpec = 'main:refs/remotes/origin/main';
+    const branchSpec = options.branch
+        ? `${options.branch}:refs/remotes/origin/${options.branch}`
+        : undefined;
+    const fetch = await run('git', ['fetch', 'origin', mainSpec]);
+    const branchFetch = branchSpec ? await run('git', ['fetch', 'origin', branchSpec]) : undefined;
+    const originMain = fetch.ok ||
+        (await run('git', ['rev-parse', '--verify', '--quiet', 'refs/remotes/origin/main'])).ok;
+    const branchResult = await run('git', ['branch', '--show-current']);
+    const localBranch = text(branchResult) || 'unavailable';
+    const selector = options.noPr ? undefined : (options.pr ?? options.branch);
+    const ghArgs = selector ? ['pr', 'view', selector, '--json', PR_JSON_FIELDS] : undefined;
+    const gh = ghArgs ? await run('gh', ghArgs) : undefined;
+    const data = gh?.ok ? readJson(gh.stdout) : undefined;
+    const state = options.noPr
+        ? 'none'
+        : stringField(data, 'state', gh?.ok ? 'unavailable' : gh ? 'gh failed' : 'unavailable');
+    const head = stringField(data, 'headRefName');
+    const branch = options.branch ??
+        (options.pr && head !== 'unavailable' ? head : options.noPr ? localBranch : 'unavailable');
+    const rangeName = options.branch ?? (options.noPr ? localBranch : undefined);
+    const localRange = options.noPr && options.branch === undefined && localBranch === 'unavailable'
+        ? 'HEAD'
+        : rangeName;
+    const resolved = localRange
+        ? await resolveNamedRef(localRange, run, localRange === options.branch && branchFetch?.ok === true)
+        : unresolvedRange();
+    const range = resolved.range;
+    const commitsResult = !data && range && originMain
+        ? await run('git', ['rev-list', '--count', `origin/main..${range}`])
+        : undefined;
+    const diffResult = !data && range && originMain
+        ? await run('git', ['diff', '--name-only', `origin/main...${range}`])
+        : undefined;
+    const scoped = Boolean(options.branch &&
+        (localBranch !== options.branch || (head !== 'unavailable' && head !== options.branch))) || Boolean(options.pr && !options.branch && (head === 'unavailable' || head !== localBranch));
+    const scope = options.branch ?? `#${options.pr}`;
+    const status = scoped
+        ? undefined
+        : await run('git', ['status', '--porcelain', '--untracked-files=normal']);
+    const reflog = scoped || branch === 'unavailable'
+        ? undefined
+        : await run('git', ['reflog', 'show', `origin/${branch}`]);
+    const merge = objectField(data, 'mergeCommit', 'oid');
+    const merged = await mergeFact(data, state, merge, resolved.range, originMain, options, run);
+    const filesText = diffResult?.ok ? text(diffResult) : undefined;
+    const raw = options.raw
+        ? `\n=== Raw Command Output ===\n${calls.map((call) => rawBlock(call.command, call.args, call.result)).join('')}`
+        : '';
+    return format({
+        fetch: `git fetch origin ${mainSpec}${branchSpec ? `; git fetch origin ${branchSpec}` : ''}`,
+        fetchStatus: fetch.ok ? 'ok' : 'failed',
+        fetchNote: `${fetch.ok
+            ? 'origin/main refreshed'
+            : originMain
+                ? 'using existing local origin/main ref after failed fetch'
+                : 'origin/main unavailable after failed fetch'}${resolved.refreshed ? `; origin/${localRange} refreshed` : ''}`,
+        branch,
+        pr: options.noPr ? 'none' : stringField(data, 'number'),
+        state,
+        mergedAt: stringField(data, 'mergedAt'),
+        mergeCommit: merge,
+        merged,
+        commits: data ? 'unavailable' : commitsResult?.ok ? text(commitsResult) : 'unavailable',
+        prCommits: data ? count(data, 'commits') : undefined,
+        files: data
+            ? apiFiles(data)
+            : filesText === undefined
+                ? 'unavailable'
+                : String(lines(filesText).length),
+        dirs: data ? dirs(data) : filesText === undefined ? 'unavailable' : topDirs(filesText),
+        changeSource: data ? 'api' : 'local',
+        remote: reflog === undefined
+            ? undefined
+            : reflog.ok
+                ? String(lines(text(reflog)).length)
+                : 'unavailable',
+        pushes: reflog === undefined
+            ? undefined
+            : reflog.ok
+                ? String(lines(text(reflog)).filter((line) => line.includes('update by push')).length)
+                : 'unavailable',
+        ...(scoped ? { scoped: scope } : {}),
+        working: status === undefined
+            ? undefined
+            : status.ok
+                ? String(lines(text(status)).length)
+                : 'unavailable',
+    }, raw);
+}
+function text(result) {
+    return result.stdout.trim();
+}
+function lines(value) {
+    return value.split('\n').filter(Boolean);
+}
+async function resolveNamedRef(name, run, fetched = false) {
+    if (name === 'HEAD')
+        return { range: name, refreshed: false };
+    if ((await run('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${name}`])).ok)
+        return { range: name, refreshed: false };
+    const fetch = fetched
+        ? { ok: true, stdout: '', stderr: '' }
+        : await run('git', ['fetch', 'origin', `${name}:refs/remotes/origin/${name}`]);
+    if (!fetch.ok)
+        return { range: undefined, refreshed: false };
+    if ((await run('git', ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${name}`])).ok)
+        return { range: `origin/${name}`, refreshed: true };
+    return { range: undefined, refreshed: false };
+}
+function unresolvedRange() {
+    return { range: undefined, refreshed: false };
+}
+async function mergeFact(data, state, merge, range, originMain, options, run) {
+    if (merge && originMain) {
+        const inOrigin = await run('git', ['merge-base', '--is-ancestor', merge, 'origin/main']);
+        if (!inOrigin.ok)
+            return inOrigin.exitCode === 1 ? `no (origin/main lacks ${merge})` : 'unavailable';
+        const inLocalMain = await run('git', ['merge-base', '--is-ancestor', merge, 'main']);
+        if (!inLocalMain.ok && inLocalMain.exitCode === 1)
+            options.onWarning?.(`Warning: local main lacks PR merge commit ${merge}, but origin/main contains it.`);
+        return `yes (origin/main contains ${merge})`;
+    }
+    if (data && (state === 'OPEN' || state === 'CLOSED'))
+        return 'unmerged at time of retro';
+    if (!data && range && originMain) {
+        const rangeInOrigin = await run('git', ['merge-base', '--is-ancestor', range, 'origin/main']);
+        if (rangeInOrigin.ok)
+            return `yes (origin/main contains ${range})`;
+        if (rangeInOrigin.exitCode === 1)
+            return `no (origin/main lacks ${range})`;
+    }
+    return 'unavailable';
+}

package/dist/retrospective-facts/shared.d.mts

@@ -0,0 +1,17 @@
+export declare const PR_JSON_FIELDS = "number,state,mergedAt,mergeCommit,changedFiles,files,commits,headRefName,baseRefName";
+export type CommandResult = {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode?: number | null;
+};
+export type CommandExecutor = (command: string, args: string[]) => Promise<CommandResult>;
+export type RetrospectiveFactsOptions = {
+    pr?: string;
+    branch?: string;
+    noPr?: boolean;
+    repo?: string;
+    raw?: boolean;
+    execute?: CommandExecutor;
+    onWarning?: (message: string) => void;
+};

package/dist/retrospective-facts/shared.mjs

@@ -0,0 +1 @@
+export const PR_JSON_FIELDS = 'number,state,mergedAt,mergeCommit,changedFiles,files,commits,headRefName,baseRefName';

package/dist/skill-discovery/index.d.mts

@@ -0,0 +1,12 @@
+export { readSkillManifest, type SkillManifest, type SkillManifestEntry } from './manifest.mts';
+export type LinkSkillOptions = {
+    name: string;
+    sourceRoot: string;
+    targetRoot: string;
+};
+export type LinkSkillResult = {
+    created: boolean;
+    path: string;
+    source: string;
+};
+export declare function linkSkill(options: LinkSkillOptions): Promise<LinkSkillResult>;

package/dist/skill-discovery/index.mjs

@@ -0,0 +1,64 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { linkDirectoryEntry, resolveTargetDirectory, } from './target-directory.mjs';
+import { assertContained, isContained, isSafeSkillName, readSkillManifest, } from './manifest.mjs';
+export { readSkillManifest } from './manifest.mjs';
+export async function linkSkill(options) {
+    if (!isSafeSkillName(options.name))
+        throw new Error(`Invalid skill name: ${options.name}`);
+    const sourceRoot = resolve(options.sourceRoot);
+    const canonicalSourceRoot = await realpath(sourceRoot);
+    const manifest = await readSkillManifest(sourceRoot);
+    const entry = manifest.skills.find((candidate) => candidate.name === options.name);
+    if (entry === undefined)
+        throw new Error(`Unknown skill: ${options.name}`);
+    const targetRoot = await resolveTargetDirectory(options.targetRoot);
+    const linked = new Set();
+    const linking = new Set();
+    return linkManifestSkill(sourceRoot, canonicalSourceRoot, targetRoot, manifest, entry, linked, linking);
+}
+async function linkManifestSkill(sourceRoot, canonicalSourceRoot, targetRoot, manifest, entry, linked, linking) {
+    if (linked.has(entry.name))
+        return linkResult(targetRoot, entry.name, sourceRoot, canonicalSourceRoot, entry.path);
+    if (linking.has(entry.name))
+        throw new Error(`Circular skill prerequisite: ${entry.name}`);
+    linking.add(entry.name);
+    try {
+        for (const prerequisite of prerequisitesFor(manifest, entry)) {
+            await linkManifestSkill(sourceRoot, canonicalSourceRoot, targetRoot, manifest, prerequisite, linked, linking);
+        }
+        const result = await linkResult(targetRoot, entry.name, sourceRoot, canonicalSourceRoot, entry.path);
+        linked.add(entry.name);
+        return result;
+    }
+    finally {
+        linking.delete(entry.name);
+    }
+}
+async function linkResult(targetRoot, name, sourceRoot, canonicalSourceRoot, skillPath) {
+    const source = await resolveSkillSource(sourceRoot, canonicalSourceRoot, skillPath);
+    const path = assertContained(targetRoot.path, name);
+    return { created: await linkDirectoryEntry(source, targetRoot, name), path, source };
+}
+function prerequisitesFor(manifest, entry) {
+    const entriesByName = new Map(manifest.skills.map((candidate) => [candidate.name, candidate]));
+    return (entry.prerequisites ?? []).map((name) => entriesByName.get(name));
+}
+async function resolveSkillSource(sourceRoot, canonicalSourceRoot, skillPath) {
+    const candidate = assertContained(sourceRoot, skillPath);
+    let skill;
+    try {
+        skill = await realpath(candidate);
+    }
+    catch {
+        /* v8 ignore next 2 -- only an attacker replacing a validated source can reach this. */
+        throw new Error(`Invalid skill source: ${skillPath}`);
+    }
+    /* v8 ignore next 2 -- only an attacker replacing a validated source can reach this. */
+    if (!isContained(canonicalSourceRoot, skill) || !(await lstat(skill)).isFile())
+        throw new Error(`Skill source escapes root: ${skillPath}`);
+    // Validate through the canonical path, but retain the caller's logical root in
+    // the link target. Package managers replace their physical store paths during
+    // upgrades while the logical installed path remains stable.
+    return dirname(candidate);
+}

package/dist/skill-discovery/manifest.d.mts

@@ -0,0 +1,15 @@
+export type SkillManifestEntry = {
+    name: string;
+    plugin: string;
+    pluginVersion: string;
+    path: string;
+    prerequisites?: string[];
+};
+export type SkillManifest = {
+    version: 1;
+    skills: SkillManifestEntry[];
+};
+export declare function readSkillManifest(sourceRoot: string): Promise<SkillManifest>;
+export declare function assertContained(root: string, child: string): string;
+export declare function isSafeSkillName(name: string): boolean;
+export declare function isContained(root: string, path: string): boolean;

package/dist/skill-discovery/manifest.mjs

@@ -0,0 +1,85 @@
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { basename, isAbsolute, relative, resolve, join } from 'node:path';
+export async function readSkillManifest(sourceRoot) {
+    const root = await realpath(resolve(sourceRoot));
+    const parsed = JSON.parse(await readFile(join(root, 'manifest.json'), 'utf8'));
+    if (!isManifest(parsed))
+        throw new Error('Invalid skills manifest');
+    await validateManifestEntries(root, parsed.skills);
+    return parsed;
+}
+export function assertContained(root, child) {
+    if (isAbsolute(child))
+        throw new Error(`Skill path escapes root: ${child}`);
+    const path = resolve(root, child);
+    if (!isContained(root, path))
+        throw new Error(`Skill path escapes root: ${child}`);
+    return path;
+}
+export function isSafeSkillName(name) {
+    return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);
+}
+export function isContained(root, path) {
+    const pathRelative = relative(root, path);
+    return !pathRelative.startsWith('..') && !isAbsolute(pathRelative);
+}
+async function validateManifestEntries(root, entries) {
+    const names = new Set();
+    const lexicalPaths = new Set();
+    const canonicalPaths = new Set();
+    for (const entry of entries) {
+        if (!isSafeSkillName(entry.name))
+            throw new Error(`Invalid skill name: ${entry.name}`);
+        if (names.has(entry.name))
+            throw new Error(`Duplicate skill name: ${entry.name}`);
+        names.add(entry.name);
+        const prerequisites = entry.prerequisites ?? [];
+        if (new Set(prerequisites).size !== prerequisites.length)
+            throw new Error(`Duplicate skill prerequisite: ${entry.name}`);
+        for (const prerequisite of prerequisites) {
+            if (!isSafeSkillName(prerequisite))
+                throw new Error(`Invalid skill prerequisite: ${prerequisite}`);
+        }
+        if (basename(entry.path) !== 'SKILL.md')
+            throw new Error(`Invalid skill source: ${entry.path}`);
+        const path = assertContained(root, entry.path);
+        if (lexicalPaths.has(path))
+            throw new Error(`Duplicate skill path: ${entry.path}`);
+        lexicalPaths.add(path);
+        let canonicalPath;
+        try {
+            canonicalPath = await realpath(path);
+        }
+        catch {
+            throw new Error(`Invalid skill source: ${entry.path}`);
+        }
+        if (!isContained(root, canonicalPath))
+            throw new Error(`Skill source escapes root: ${entry.path}`);
+        if (!(await lstat(canonicalPath)).isFile())
+            throw new Error(`Invalid skill source: ${entry.path}`);
+        if (canonicalPaths.has(canonicalPath))
+            throw new Error(`Duplicate skill path: ${entry.path}`);
+        canonicalPaths.add(canonicalPath);
+    }
+    for (const entry of entries) {
+        for (const prerequisite of entry.prerequisites ?? []) {
+            if (!names.has(prerequisite))
+                throw new Error(`Missing prerequisite skill: ${prerequisite}`);
+        }
+    }
+}
+function isManifest(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const manifest = value;
+    return manifest.version === 1 && Array.isArray(manifest.skills) && manifest.skills.every(isEntry);
+}
+function isEntry(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const entry = value;
+    return ([entry.name, entry.plugin, entry.pluginVersion, entry.path].every((field) => typeof field === 'string' && field.length > 0) &&
+        (entry.prerequisites === undefined ||
+            (Array.isArray(entry.prerequisites) &&
+                entry.prerequisites.every((name) => typeof name === 'string'))));
+}

package/dist/skill-discovery/target-directory.d.mts

@@ -0,0 +1,10 @@
+export type TargetDirectory = {
+    path: string;
+    dev: bigint;
+    ino: bigint;
+};
+export declare function resolveTargetDirectory(targetRoot: string, beforeRevalidate?: () => Promise<void>): Promise<TargetDirectory>;
+export declare function linkDirectoryEntry(source: string, target: TargetDirectory, name: string, beforeWorker?: () => Promise<void>, worker?: DirectoryLinkWorker, afterWorker?: () => Promise<void>): Promise<boolean>;
+type DirectoryLinkWorker = (source: string, target: TargetDirectory, name: string) => Promise<string>;
+export declare function snapshotTargetDirectory(path: string): Promise<TargetDirectory>;
+export {};