@qvac/harness 0.1.0 → 0.1.2

package/dist-lib/lib/tools/skills/catalog.d.ts

@@ -0,0 +1,60 @@
+import type { CredentialStoreFn } from './auth-resolver.ts';
+import type { SkillSettingsFn } from './skill-settings.ts';
+import type { InstallStep, SkillRequires, SkillSetup } from './manifest.ts';
+import { type CliValidator } from './cli-schema.ts';
+import { type SkillState } from './skill-state.ts';
+import type { BinVersionState } from './bin-check.ts';
+import { type CredentialCheckFetch } from './credential-check.ts';
+import { type OperationSpec } from '../operations/manifest.ts';
+import type { CapabilityProfile } from '../../models/model-catalog.ts';
+export interface SkillCatalogEntry {
+    name: string;
+    description: string;
+    aliases?: string[];
+    preloadOnName?: boolean;
+    tools: string[];
+    credentials: string[];
+    allowList: string[];
+    mcpReads?: string[];
+    platform: string[];
+    requires?: SkillRequires;
+    install?: InstallStep[];
+    setup?: SkillSetup;
+    cliValidator?: CliValidator;
+    stub?: boolean;
+    minCapabilityProfile?: string;
+    emoji?: string;
+    referenceFiles?: string[];
+    operations?: readonly OperationSpec[];
+    origin?: 'overlay';
+}
+export interface ResolvedSkillCatalogEntry extends SkillCatalogEntry {
+    status: SkillState;
+}
+export declare function skillSupportsPlatform(entry: SkillCatalogEntry, platform: string | undefined): boolean;
+export declare function versionProbeSkills(catalog: readonly SkillCatalogEntry[], installedTools: ReadonlySet<string>, platform: string | undefined): SkillCatalogEntry[];
+export declare function availableSkills(catalog: readonly SkillCatalogEntry[], installedTools: ReadonlySet<string>, activeProfile?: CapabilityProfile): SkillCatalogEntry[];
+export interface ResolveSkillStatusOptions {
+    installedTools?: ReadonlySet<string>;
+    credentialStore?: CredentialStoreFn;
+    settingsStore?: SkillSettingsFn;
+    platform?: string;
+    agentId?: string | null;
+    activeProfile?: CapabilityProfile;
+    binVersions?: ReadonlyMap<string, ReadonlyMap<string, BinVersionState>>;
+    refresh?: boolean;
+    skipCredentialProbe?: boolean;
+    fetchImpl?: CredentialCheckFetch;
+}
+export declare function skillsEligibleForCredentialProbe(catalog: readonly SkillCatalogEntry[], { platform, installedTools }?: {
+    platform?: string | undefined;
+    installedTools?: ReadonlySet<string> | undefined;
+}): SkillCatalogEntry[];
+export declare function resolveSkillStatuses(catalog: readonly SkillCatalogEntry[], { installedTools, credentialStore, settingsStore, platform, agentId, activeProfile, binVersions, refresh, skipCredentialProbe, fetchImpl }?: ResolveSkillStatusOptions): Promise<ResolvedSkillCatalogEntry[]>;
+export interface LoadSkillCatalogOptions {
+    platform?: string | null;
+    overlayDir?: string | null;
+}
+export declare function loadSkillCatalog(skillsDir: string, { platform, overlayDir }?: LoadSkillCatalogOptions): Promise<SkillCatalogEntry[]>;
+export declare function mcpReadMethods(catalog: readonly SkillCatalogEntry[]): ReadonlyMap<string, ReadonlySet<string>>;
+export declare function detectPlatform(): string;

package/dist-lib/lib/tools/skills/catalog.js

@@ -0,0 +1,203 @@
+import fs from 'fs';
+import { platform } from 'os';
+import path from 'path';
+import { parseSkillFrontMatter } from "./frontmatter-parser.js";
+import { buildCliValidator, loadSkillCli } from "./cli-schema.js";
+import { isModelCompatible, isStub, isToolSupported, resolveSkillState, SKILL_STATE, supportsPlatform } from "./skill-state.js";
+import { validateCredentialChecks } from "./credential-check.js";
+import { OBSIDIAN_SKILL_NAME } from "./obsidian-readiness.js";
+import { parseToolGrant } from "./tool-grants.js";
+import { deriveSetup } from "./setup-routes.js";
+import { resolveSkillsOverlayDir } from "./overlay-dir.js";
+import { parseOperationsManifest } from "../operations/manifest.js";
+import { hlog } from "../../log.js";
+export function skillSupportsPlatform(entry, platform) {
+    return supportsPlatform(entry, platform);
+}
+export function versionProbeSkills(catalog, installedTools, platform) {
+    return catalog.filter((entry) => entry.name !== OBSIDIAN_SKILL_NAME &&
+        entry.requires?.binMinVersions &&
+        skillSupportsPlatform(entry, platform) &&
+        !entry.stub &&
+        entry.tools.every((name) => installedTools.has(parseToolGrant(name).name)));
+}
+export function availableSkills(catalog, installedTools, activeProfile) {
+    return catalog.filter((skill) => !isStub(skill) &&
+        isToolSupported(skill, installedTools) &&
+        isModelCompatible(skill, activeProfile));
+}
+export function skillsEligibleForCredentialProbe(catalog, { platform, installedTools } = {}) {
+    return catalog.filter((entry) => supportsPlatform(entry, platform) &&
+        !isStub(entry) &&
+        (!installedTools || isToolSupported(entry, installedTools)));
+}
+export function resolveSkillStatuses(catalog, { installedTools, credentialStore, settingsStore, platform, agentId, activeProfile, binVersions, refresh, skipCredentialProbe, fetchImpl } = {}) {
+    const probeCatalog = skillsEligibleForCredentialProbe(catalog, { platform, installedTools });
+    const checked = skipCredentialProbe
+        ? Promise.resolve()
+        : validateCredentialChecks(probeCatalog, credentialStore, agentId, fetchImpl, { refresh });
+    return checked.then(() => Promise.all(catalog.map(async (entry) => withSetup(entry, installedTools && !isToolSupported(entry, installedTools)
+        ? SKILL_STATE.unsupported
+        : await resolveSkillState(entry, {
+            credentialStore,
+            settingsStore,
+            platform,
+            agentId,
+            activeProfile,
+            binVersions: binVersions?.get(entry.name)
+        })))));
+}
+function withSetup(entry, state) {
+    const { install, setup: _setup, requires, ...rest } = entry;
+    const setup = deriveSetup(entry, state);
+    return {
+        ...rest,
+        ...(requires ? { requires: stripCredentialChecks(requires) } : {}),
+        ...(install ? { install } : {}),
+        ...(setup ? { setup } : {}),
+        status: state
+    };
+}
+function stripCredentialChecks(requires) {
+    const { credentialChecks: _drop, ...rest } = requires;
+    return rest;
+}
+export async function loadSkillCatalog(skillsDir, { platform = detectPlatform(), overlayDir = resolveSkillsOverlayDir() } = {}) {
+    const byName = await loadRoot(skillsDir);
+    if (overlayDir) {
+        for (const [name, overlay] of await loadRoot(overlayDir, 'overlay')) {
+            byName.set(name, mergeOverlay(byName.get(name), overlay));
+        }
+    }
+    return [...byName.values()]
+        .filter((entry) => skillSupportsPlatform(entry, platform ?? undefined))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function mergeOverlay(base, overlay) {
+    if (!base)
+        return overlay;
+    const { origin: _origin, mcpReads: _mcpReads, operations: _operations, ...rest } = overlay;
+    return {
+        ...rest,
+        credentials: base.credentials,
+        allowList: base.allowList,
+        platform: base.platform,
+        ...(base.operations ? { operations: base.operations } : {}),
+        ...(base.mcpReads ? { mcpReads: base.mcpReads } : {})
+    };
+}
+const OVERLAY_DEFAULT_PLATFORMS = ['darwin', 'linux', 'win32', 'ios', 'android'];
+async function loadRoot(skillsDir, origin) {
+    let dirs;
+    try {
+        dirs = (await fs.promises.readdir(skillsDir, { withFileTypes: true }))
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return new Map();
+    }
+    const loaded = await Promise.all(dirs.map((dir) => loadEntry(skillsDir, dir, origin)));
+    const byName = new Map();
+    for (const entry of loaded)
+        if (entry)
+            byName.set(entry.name, entry);
+    return byName;
+}
+export function mcpReadMethods(catalog) {
+    const byHost = new Map();
+    for (const entry of catalog) {
+        if (entry.origin === 'overlay')
+            continue;
+        if (!entry.mcpReads || entry.mcpReads.length === 0)
+            continue;
+        for (const url of entry.allowList) {
+            const host = hostnameOf(url);
+            if (!host)
+                continue;
+            const methods = byHost.get(host) ?? new Set();
+            for (const method of entry.mcpReads)
+                methods.add(method);
+            byHost.set(host, methods);
+        }
+    }
+    return byHost;
+}
+function hostnameOf(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return null;
+    }
+}
+export function detectPlatform() {
+    return platform();
+}
+async function loadEntry(skillsDir, dir, origin) {
+    try {
+        const skillDir = path.join(skillsDir, dir);
+        const raw = await fs.promises.readFile(path.join(skillDir, 'SKILL.md'), 'utf8');
+        const { meta } = parseSkillFrontMatter(raw);
+        const tools = meta.tools ?? [];
+        const cli = await loadSkillCli(skillDir, tools);
+        const referenceFiles = await loadReferenceFiles(skillDir);
+        const operations = origin === 'overlay' ? [] : await loadOperations(skillDir, dir);
+        const platform = meta.platform && meta.platform.length > 0
+            ? meta.platform
+            : origin === 'overlay'
+                ? OVERLAY_DEFAULT_PLATFORMS
+                : [];
+        return {
+            name: dir,
+            description: meta.description ?? '',
+            ...(meta.aliases ? { aliases: meta.aliases } : {}),
+            ...(meta.preloadOnName === false ? { preloadOnName: false } : {}),
+            tools,
+            credentials: meta.credentials ?? [],
+            allowList: meta.allowList ?? [],
+            ...(meta.mcpReads ? { mcpReads: meta.mcpReads } : {}),
+            platform,
+            ...(meta.requires ? { requires: meta.requires } : {}),
+            ...(meta.install ? { install: meta.install } : {}),
+            ...(meta.setup ? { setup: meta.setup } : {}),
+            ...(cli ? { cliValidator: buildCliValidator(cli) } : {}),
+            ...(meta.stub !== undefined ? { stub: meta.stub } : {}),
+            ...(meta.minCapabilityProfile ? { minCapabilityProfile: meta.minCapabilityProfile } : {}),
+            ...(meta.emoji ? { emoji: meta.emoji } : {}),
+            ...(referenceFiles.length ? { referenceFiles } : {}),
+            ...(operations.length ? { operations } : {}),
+            ...(origin ? { origin } : {})
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function loadOperations(skillDir, name) {
+    let raw;
+    try {
+        raw = await fs.promises.readFile(path.join(skillDir, 'operations.json'), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const operations = parseOperationsManifest(raw);
+    if (!operations) {
+        hlog('skill operations manifest rejected', { skill: name });
+        return [];
+    }
+    return operations;
+}
+async function loadReferenceFiles(skillDir) {
+    try {
+        const entries = await fs.promises.readdir(path.join(skillDir, 'references'));
+        return entries
+            .filter((entry) => entry.endsWith('.md'))
+            .sort()
+            .map((entry) => `references/${entry}`);
+    }
+    catch {
+        return [];
+    }
+}

package/dist-lib/lib/tools/skills/cli-argv.d.ts

@@ -0,0 +1,9 @@
+import type { JsonSchema } from './cli-schema-types.ts';
+export declare function walkCommands(argv: readonly string[], schema: JsonSchema): {
+    node: JsonSchema;
+    pathSegs: string[];
+    index: number;
+};
+export declare function argvToObject(argv: readonly string[], schema: JsonSchema): Record<string, unknown> | string;
+export declare function objectProps(schema: JsonSchema): Readonly<Record<string, JsonSchema>>;
+export declare function isObjectSchema(schema: JsonSchema): boolean;

package/dist-lib/lib/tools/skills/cli-argv.js

@@ -0,0 +1,147 @@
+export function walkCommands(argv, schema) {
+    let node = schema;
+    const pathSegs = [];
+    let i = 0;
+    while (i < argv.length) {
+        const tok = argv[i] ?? '';
+        if (isParamToken(tok))
+            break;
+        const child = objectProps(node)[tok];
+        if (!child || !isObjectSchema(child))
+            break;
+        pathSegs.push(tok);
+        node = child;
+        i++;
+    }
+    return { node, pathSegs, index: i };
+}
+export function argvToObject(argv, schema) {
+    const { node, pathSegs, index } = walkCommands(argv, schema);
+    const leaf = parseParams(argv.slice(index), node);
+    if (typeof leaf === 'string')
+        return leaf;
+    let out = leaf;
+    for (let p = pathSegs.length - 1; p >= 0; p--) {
+        out = { [pathSegs[p]]: out };
+    }
+    return out;
+}
+export function objectProps(schema) {
+    return schema.properties ?? {};
+}
+export function isObjectSchema(schema) {
+    return schema.type === 'object' || (!schema.type && !!schema.properties);
+}
+function isParamToken(tok) {
+    if (!tok)
+        return false;
+    if (tok.startsWith('-'))
+        return true;
+    if (tok.includes('='))
+        return true;
+    return false;
+}
+function parseParams(tokens, schema) {
+    const props = objectProps(schema);
+    const propKeys = new Set(Object.keys(props));
+    const boolKeys = new Set(Object.entries(props)
+        .filter(([, s]) => s.type === 'boolean')
+        .map(([k]) => k));
+    const positionals = schema['x-positionals'] ?? [];
+    const restName = schema['x-rest'];
+    const out = {};
+    let posIdx = 0;
+    const restVals = [];
+    let i = 0;
+    while (i < tokens.length) {
+        const tok = tokens[i] ?? '';
+        const canAbsorb = posIdx < positionals.length || restName !== undefined;
+        const eq = tok.indexOf('=');
+        if (eq > 0 && !tok.startsWith('-')) {
+            const key = tok.slice(0, eq);
+            if (propKeys.has(key)) {
+                out[key] = coerce(tok.slice(eq + 1), props[key]);
+                i++;
+                continue;
+            }
+            if (!canAbsorb)
+                return `unknown parameter "${key}"`;
+        }
+        if (tok.startsWith('-')) {
+            let key;
+            let inline;
+            if (tok.startsWith('--')) {
+                const body = tok.slice(2);
+                const ieq = body.indexOf('=');
+                if (ieq >= 0) {
+                    key = body.slice(0, ieq);
+                    inline = body.slice(ieq + 1);
+                }
+                else
+                    key = body;
+            }
+            else {
+                key = tok.slice(1);
+            }
+            if (propKeys.has(key)) {
+                if (boolKeys.has(key)) {
+                    out[key] = inline !== undefined ? inline !== 'false' && inline !== '0' : true;
+                    i++;
+                    continue;
+                }
+                if (inline !== undefined) {
+                    out[key] = coerce(inline, props[key]);
+                    i++;
+                    continue;
+                }
+                const next = tokens[i + 1];
+                if (next === undefined || next.startsWith('-')) {
+                    return `flag --${key} requires a value`;
+                }
+                out[key] = coerce(next, props[key]);
+                i += 2;
+                continue;
+            }
+            if (!canAbsorb)
+                return `unknown flag "--${key}"`;
+        }
+        if (boolKeys.has(tok)) {
+            out[tok] = true;
+            i++;
+            continue;
+        }
+        if (propKeys.has(tok) && props[tok]?.type === 'string' && !canAbsorb) {
+            out[tok] = '';
+            i++;
+            continue;
+        }
+        if (posIdx < positionals.length) {
+            const name = positionals[posIdx];
+            if (!propKeys.has(name))
+                return `x-positionals names unknown property "${name}"`;
+            out[name] = coerce(tok, props[name]);
+            posIdx++;
+            i++;
+            continue;
+        }
+        if (restName) {
+            restVals.push(tok);
+            i++;
+            continue;
+        }
+        return `unexpected argument "${tok}"`;
+    }
+    if (restName && restVals.length > 0)
+        out[restName] = restVals;
+    return out;
+}
+function coerce(value, schema) {
+    if (schema.type === 'number' || schema.type === 'integer') {
+        const n = Number(value);
+        return Number.isFinite(n) ? n : value;
+    }
+    if (schema.type === 'boolean') {
+        return value !== 'false' && value !== '0';
+    }
+    return value;
+}

package/dist-lib/lib/tools/skills/cli-schema-check.d.ts

@@ -0,0 +1,3 @@
+import type { JsonSchema } from './cli-schema-types.ts';
+export declare function buildSchemaAnnotation(schema: JsonSchema): (argv: readonly string[]) => 'read' | 'write';
+export declare function buildSchemaCheck(schema: JsonSchema, resourcePaths: readonly string[] | undefined): (argv: readonly string[]) => string | null;

package/dist-lib/lib/tools/skills/cli-schema-check.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { argvToObject, isObjectSchema, objectProps, walkCommands } from "./cli-argv.js";
+export function buildSchemaAnnotation(schema) {
+    const resourceEffects = schema['x-resource-effects'];
+    return (argv) => {
+        const first = argv[0];
+        if (resourceEffects && typeof first === 'string') {
+            if (resourceEffects[basename(first)] === 'read')
+                return 'read';
+        }
+        return walkCommands(argv, schema).node['x-effect'] === 'read' ? 'read' : 'write';
+    };
+}
+function basename(p) {
+    return p.slice(Math.max(p.lastIndexOf('/'), p.lastIndexOf('\\')) + 1);
+}
+export function buildSchemaCheck(schema, resourcePaths) {
+    let zodSchema;
+    try {
+        zodSchema = z.fromJSONSchema(schema);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return () => `invalid skill cli JSON Schema: ${msg}`;
+    }
+    return (argv) => {
+        const built = argvToObject(argv, schema);
+        if (typeof built === 'string')
+            return built;
+        const cmdErr = assertSingleCommand(built, schema);
+        if (cmdErr)
+            return cmdErr;
+        const resourceErr = assertResourcePath(built, resourcePaths);
+        if (resourceErr)
+            return resourceErr;
+        const result = zodSchema.safeParse(built);
+        if (result.success)
+            return null;
+        return formatZod(result.error);
+    };
+}
+function assertResourcePath(obj, resourcePaths) {
+    if (!resourcePaths || resourcePaths.length === 0 || typeof obj.script !== 'string')
+        return null;
+    return resourcePaths.includes(obj.script) ? null : 'script must be a bundled skill resource';
+}
+function assertSingleCommand(obj, schema) {
+    const props = objectProps(schema);
+    const commandKeys = Object.keys(props).filter((k) => isObjectSchema(props[k]));
+    const present = commandKeys.filter((k) => k in obj);
+    if (present.length > 1) {
+        return `only one command allowed (got ${present.join(', ')})`;
+    }
+    return null;
+}
+function formatZod(err) {
+    const issue = err.issues[0];
+    if (!issue)
+        return 'invalid parameters';
+    const where = issue.path.length ? `${issue.path.join('.')}: ` : '';
+    return `${where}${issue.message}`;
+}

package/dist-lib/lib/tools/skills/cli-schema-load.d.ts

@@ -0,0 +1,4 @@
+import { type SkillCli } from './cli-schema-types.ts';
+export declare function resolveCliSchema(skillDir: string, bin: string, readFile?: (p: string) => Promise<string>): Promise<SkillCli>;
+export declare function execBinFromTools(tools: readonly string[]): string | undefined;
+export declare function loadSkillCli(skillDir: string, tools: readonly string[], readFile?: (p: string) => Promise<string>): Promise<SkillCli | undefined>;

package/dist-lib/lib/tools/skills/cli-schema-load.js

@@ -0,0 +1,90 @@
+import fs from 'fs';
+import path from 'path';
+import { CLI_SCHEMA_FILENAME } from "./cli-schema-types.js";
+export async function resolveCliSchema(skillDir, bin, readFile = (p) => fs.promises.readFile(p, 'utf8')) {
+    const full = path.join(skillDir, CLI_SCHEMA_FILENAME);
+    let raw;
+    try {
+        raw = await readFile(full);
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return { bin };
+        return { bin, schemaFile: CLI_SCHEMA_FILENAME };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isObj(parsed))
+            return { bin, schemaFile: CLI_SCHEMA_FILENAME };
+        const schema = parsed;
+        if (!resourceGuardConsistent(schema))
+            return { bin, schemaFile: CLI_SCHEMA_FILENAME };
+        if (!effectAnnotationsValid(schema))
+            return { bin, schemaFile: CLI_SCHEMA_FILENAME };
+        if (!resourceEffectsValid(schema))
+            return { bin, schemaFile: CLI_SCHEMA_FILENAME };
+        const resourcePaths = resolveResourcePaths(skillDir, schema);
+        return {
+            bin,
+            schema,
+            schemaFile: CLI_SCHEMA_FILENAME,
+            ...(resourcePaths.length ? { resourcePaths } : {})
+        };
+    }
+    catch {
+        return { bin, schemaFile: CLI_SCHEMA_FILENAME };
+    }
+}
+function resourceGuardConsistent(schema) {
+    const resources = schema['x-resource-files'];
+    if (!resources || resources.length === 0)
+        return true;
+    return schema.properties?.script?.type === 'string';
+}
+function effectAnnotationsValid(schema) {
+    if ('x-effect' in schema && schema['x-effect'] !== 'read')
+        return false;
+    return Object.values(schema.properties ?? {}).every(effectAnnotationsValid);
+}
+function resourceEffectsValid(schema) {
+    const effects = schema['x-resource-effects'];
+    if (effects === undefined)
+        return true;
+    if (typeof effects !== 'object' || effects === null || Array.isArray(effects))
+        return false;
+    const files = new Set(schema['x-resource-files'] ?? []);
+    return Object.entries(effects).every(([file, effect]) => effect === 'read' && files.has(file));
+}
+function resolveResourcePaths(skillDir, schema) {
+    const resources = schema['x-resource-files'] ?? [];
+    return resources
+        .filter((resource) => typeof resource === 'string' && /^[\w-]+\.applescript$/.test(resource))
+        .map((resource) => path.join(skillDir, resource));
+}
+export function execBinFromTools(tools) {
+    for (const entry of tools) {
+        const m = /^exec\((.+)\)$/i.exec(entry.trim());
+        const scope = m?.[1]?.trim();
+        if (scope)
+            return scope;
+    }
+    return undefined;
+}
+export async function loadSkillCli(skillDir, tools, readFile) {
+    const bin = execBinFromTools(tools);
+    if (!bin)
+        return undefined;
+    const resolved = await resolveCliSchema(skillDir, bin, readFile);
+    if (resolved.schema || resolved.schemaFile)
+        return resolved;
+    return undefined;
+}
+function isEnoent(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'code' in err &&
+        err.code === 'ENOENT');
+}
+function isObj(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/dist-lib/lib/tools/skills/cli-schema-types.d.ts

@@ -0,0 +1,30 @@
+export type JsonSchema = {
+    readonly type?: string;
+    readonly properties?: Readonly<Record<string, JsonSchema>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean | JsonSchema;
+    readonly oneOf?: readonly JsonSchema[];
+    readonly anyOf?: readonly JsonSchema[];
+    readonly enum?: readonly unknown[];
+    readonly pattern?: string;
+    readonly description?: string;
+    readonly 'x-positionals'?: readonly string[];
+    readonly 'x-rest'?: string;
+    readonly 'x-resource-files'?: readonly string[];
+    readonly 'x-resource-effects'?: Readonly<Record<string, string>>;
+    readonly 'x-effect'?: string;
+    readonly [key: string]: unknown;
+};
+export type SkillCli = {
+    readonly bin: string;
+    readonly schema?: JsonSchema;
+    readonly schemaFile?: string;
+    readonly resourcePaths?: readonly string[];
+};
+export declare const CLI_SCHEMA_FILENAME = "cli.schema.json";
+export type CliValidator = {
+    readonly bin: string;
+    readonly check: (argv: readonly string[]) => string | null;
+    readonly annotation: (argv: readonly string[]) => 'read' | 'write';
+    readonly effect: (argv: readonly string[]) => 'read' | 'write';
+};

package/dist-lib/lib/tools/skills/cli-schema-types.js

@@ -0,0 +1 @@
+export const CLI_SCHEMA_FILENAME = 'cli.schema.json';

package/dist-lib/lib/tools/skills/cli-schema.d.ts

@@ -0,0 +1,7 @@
+export type { CliValidator, JsonSchema, SkillCli } from './cli-schema-types.ts';
+export { CLI_SCHEMA_FILENAME } from './cli-schema-types.ts';
+export { argvToObject } from './cli-argv.ts';
+export { loadSkillCli, resolveCliSchema, execBinFromTools } from './cli-schema-load.ts';
+import type { CliValidator, SkillCli } from './cli-schema-types.ts';
+export declare function buildCliValidator(def: SkillCli): CliValidator;
+export declare function checkCliOps(argv: readonly string[], compiled: readonly CliValidator[]): string | null;

package/dist-lib/lib/tools/skills/cli-schema.js

@@ -0,0 +1,35 @@
+export { CLI_SCHEMA_FILENAME } from "./cli-schema-types.js";
+export { argvToObject } from "./cli-argv.js";
+export { loadSkillCli, resolveCliSchema, execBinFromTools } from "./cli-schema-load.js";
+import { buildSchemaAnnotation, buildSchemaCheck } from "./cli-schema-check.js";
+export function buildCliValidator(def) {
+    const bin = def.bin.toLowerCase();
+    if (!def.schema) {
+        return {
+            bin,
+            check: () => 'skill cli schema is missing',
+            annotation: () => 'write',
+            effect: () => 'write'
+        };
+    }
+    const check = buildSchemaCheck(def.schema, def.resourcePaths);
+    const annotation = buildSchemaAnnotation(def.schema);
+    return {
+        bin,
+        check,
+        annotation,
+        effect: (argv) => (check(argv) === null ? annotation(argv) : 'write')
+    };
+}
+export function checkCliOps(argv, compiled) {
+    if (compiled.length === 0)
+        return null;
+    let lastErr = null;
+    for (const c of compiled) {
+        const err = c.check(argv);
+        if (err === null)
+            return null;
+        lastErr = err;
+    }
+    return lastErr ?? 'command does not match any allowed skill operation';
+}