@qvac/harness 0.3.3 → 0.5.0

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

@@ -1,8 +1,9 @@
 import { raceAbort } from '../../helpers/race-abort.js';
-import { parseObjectArg } from '../http-request/utils.js';
+import { parseObjectArg } from '../http-request/request.js';
 export function credentialRecord(value) {
-    if (typeof value === 'string')
+    if (typeof value === 'string') {
         return value ? { token: value } : null;
+    }
     return value?.token ? value : null;
 }
 export function isCredentialExpired(record, now = Date.now()) {
@@ -23,8 +24,9 @@ function matchesPattern(url, pattern) {
     catch {
         return url.href.startsWith(raw);
     }
-    if (url.protocol !== base.protocol || url.host !== base.host)
+    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) {
@@ -40,10 +42,12 @@ export function isCredentialUrlAllowed(target, patterns) {
 }
 export function parseAuth(v) {
     const parsed = parseObjectArg(v, 'auth');
-    if (!parsed.ok)
+    if (!parsed.ok) {
         return parsed;
-    if (!parsed.value)
+    }
+    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)}` };
@@ -69,8 +73,9 @@ async function connectedCredentials(keys, credentialStore, ctx) {
     const connected = [];
     for (const key of keys) {
         const record = credentialRecord(await credentialStore(key, ctx));
-        if (record)
+        if (record) {
             connected.push({ token: record.token, key });
+        }
     }
     return connected;
 }
@@ -79,7 +84,7 @@ function ambiguous(keys) {
         error: `multiple credentials match this URL; set auth.tokenCredentialKey to one of ${keys.join(', ')}`
     };
 }
-async function resolveGuessedKey(key, url, credentialStore, credentialAllowList, ctx) {
+async function resolveGuessedKey(key, url, { credentialStore, credentialAllowList = {}, ctx }) {
     const granted = grantedKeys(url, credentialAllowList);
     if (granted.length === 0) {
         return {
@@ -92,14 +97,16 @@ async function resolveGuessedKey(key, url, credentialStore, credentialAllowList,
             error: `unknown credential key ${key}; no connected credential for ${url.host} (${granted.join(', ')}). Tell the user to connect it in Skills; do not retry`
         };
     }
-    if (rest.length > 0)
+    if (rest.length > 0) {
         return ambiguous([first, ...rest].map((c) => c.key));
+    }
     return first;
 }
-async function resolveDeclaredKey(key, url, credentialStore, credentialAllowList, ctx) {
+async function resolveDeclaredKey(key, url, { credentialStore, credentialAllowList, ctx }) {
     const entry = credentialAllowList?.[key];
-    if (!entry)
+    if (!entry) {
         return null;
+    }
     const patterns = Array.isArray(entry) ? entry : [entry];
     if (!urlAllowed(url, patterns)) {
         return { error: `credential ${key} is not allowed for URL ${url.href}` };
@@ -114,37 +121,42 @@ async function resolveDeclaredKey(key, url, credentialStore, credentialAllowList
 }
 export async function resolveAuth(auth, url, credentialStore, credentialAllowList, ctx) {
     const key = auth.tokenCredentialKey;
-    if (!credentialStore)
+    if (!credentialStore) {
         return { error: 'credentials not configured' };
-    return ((await resolveDeclaredKey(key, url, credentialStore, credentialAllowList, ctx)) ??
-        resolveGuessedKey(key, url, credentialStore, credentialAllowList ?? {}, ctx));
+    }
+    const access = { credentialStore, credentialAllowList, ctx };
+    return (await resolveDeclaredKey(key, url, access)) ?? resolveGuessedKey(key, url, access);
 }
 export async function resolveAutoAuth(url, credentialStore, credentialAllowList, ctx) {
     if (!credentialStore || !credentialAllowList)
         return null;
     const connected = await connectedCredentials(grantedKeys(url, credentialAllowList), credentialStore, ctx);
-    if (connected.length > 1)
+    if (connected.length > 1) {
         return ambiguous(connected.map((c) => c.key));
+    }
     return connected[0] ?? null;
 }
 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)
+        if ('error' in resolved) {
             return { error: resolved.error };
+        }
         return { header: `Bearer ${resolved.token}`, credentialKey: resolved.key };
     }
     const resolved = await raceAbort(resolveAutoAuth(url, credentialStore, credentialAllowList, ctx), signal);
-    if (resolved && 'error' in resolved)
+    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 || !credentialStore)
+    if (!auth || !credentialStore) {
         return { header: null };
-    const resolved = await raceAbort(resolveDeclaredKey(auth.tokenCredentialKey, url, credentialStore, credentialAllowList, ctx), signal);
+    }
+    const resolved = await raceAbort(resolveDeclaredKey(auth.tokenCredentialKey, url, { credentialStore, credentialAllowList, ctx }), signal);
     return !resolved || 'error' in resolved
         ? { header: null }
         : { header: `Bearer ${resolved.token}`, credentialKey: resolved.key };

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

@@ -2,8 +2,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: {
+export interface ProbeBinVersionsOptions {
     platform?: string;
     run: (command: string) => Promise<string | null>;
     binPresent?: (bin: string) => boolean | Promise<boolean>;
-}): Promise<Map<string, BinVersionState>>;
+}
+export declare function probeBinVersions(requires: SkillRequires | undefined, opts: ProbeBinVersionsOptions): Promise<Map<string, BinVersionState>>;

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

@@ -29,20 +29,27 @@ function parseVersion(text) {
     const m = text.match(/(\d+)\.(\d+)(?:\.(\d+))?/);
     return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : null;
 }
+function versionState(found, min) {
+    if (!found || !min)
+        return 'unknown';
+    return isBelow(found, min) ? 'too-old' : 'ok';
+}
 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)
+        if (f !== m) {
             return f < m;
+        }
     }
     return false;
 }
 export async function probeBinVersions(requires, opts) {
     const states = new Map();
     const mins = requires?.binMinVersions;
-    if (!mins)
+    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)))
@@ -50,7 +57,7 @@ export async function probeBinVersions(requires, opts) {
         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');
+        states.set(bin, versionState(found, min));
     }
     return states;
 }

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

@@ -15,35 +15,42 @@ export function ensureBundledSkillsDir() {
 }
 async function materialize() {
     const dir = userTmpPath('qvac-harness-skills-' + BUNDLED_SKILLS_HASH);
-    if (await validTree(dir))
+    if (await validTree(dir)) {
         return dir;
+    }
     const staging = `${dir}-staging-${process.pid}-${randomSuffix()}`;
     await fs.promises.mkdir(staging, { recursive: true });
-    if (os.platform() !== 'win32')
+    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))
+        if (await tryRename(staging, dir)) {
             return dir;
-        if (await validTree(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))
+            if (await validTree(dir)) {
                 return dir;
+            }
             throw occupiedError(dir, err);
         }
         void fs.promises.rm(trash, { recursive: true, force: true });
-        if (await tryRename(staging, dir))
+        if (await tryRename(staging, dir)) {
             return dir;
-        if (await validTree(dir))
+        }
+        if (await validTree(dir)) {
             return dir;
+        }
         throw tamperError(dir);
     }
     finally {
@@ -81,12 +88,14 @@ async function validTree(dir) {
     try {
         if (os.platform() !== 'win32') {
             const stat = await fs.promises.lstat(dir);
-            if (!stat.isDirectory() || (stat.mode & 0o077) !== 0)
+            if (!stat.isDirectory() || (stat.mode & 0o077) !== 0) {
                 return false;
+            }
         }
         const files = await collect(dir, '');
-        if (files === null)
+        if (files === null) {
             return false;
+        }
         return hashBundledSkills(files) === BUNDLED_SKILLS_HASH;
     }
     catch {
@@ -99,8 +108,9 @@ async function collect(dir, prefix) {
         const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
         if (entry.isDirectory()) {
             const nested = await collect(path.join(dir, entry.name), rel);
-            if (nested === null)
+            if (nested === null) {
                 return null;
+            }
             files.push(...nested);
         }
         else if (entry.isFile()) {

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

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

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

@@ -1,7 +1,7 @@
 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));
+    const sorted = [...files].sort(byPath);
     for (const file of sorted) {
         hash.update(file.path);
         hash.update('\0');
@@ -10,3 +10,8 @@ export function hashBundledSkills(files) {
     }
     return hash.digest('hex').slice(0, 16);
 }
+function byPath(a, b) {
+    if (a.path < b.path)
+        return -1;
+    return a.path > b.path ? 1 : 0;
+}

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

@@ -46,10 +46,11 @@ export interface ResolveSkillStatusOptions {
     skipCredentialProbe?: boolean;
     fetchImpl?: CredentialCheckFetch;
 }
-export declare function skillsEligibleForCredentialProbe(catalog: readonly SkillCatalogEntry[], { platform, installedTools }?: {
+export interface CredentialProbeEligibilityOptions {
     platform?: string | undefined;
     installedTools?: ReadonlySet<string> | undefined;
-}): SkillCatalogEntry[];
+}
+export declare function skillsEligibleForCredentialProbe(catalog: readonly SkillCatalogEntry[], { platform, installedTools }?: CredentialProbeEligibilityOptions): 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;

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

@@ -35,7 +35,7 @@ export function resolveSkillStatuses(catalog, { installedTools, credentialStore,
     const probeCatalog = skillsEligibleForCredentialProbe(catalog, { platform, installedTools });
     const checked = skipCredentialProbe
         ? Promise.resolve()
-        : validateCredentialChecks(probeCatalog, credentialStore, agentId, fetchImpl, { refresh });
+        : 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, {
@@ -52,9 +52,9 @@ function withSetup(entry, state) {
     const setup = deriveSetup(entry, state);
     return {
         ...rest,
-        ...(requires ? { requires: stripCredentialChecks(requires) } : {}),
-        ...(install ? { install } : {}),
-        ...(setup ? { setup } : {}),
+        requires: requires ? stripCredentialChecks(requires) : undefined,
+        install,
+        setup,
         status: state
     };
 }
@@ -82,8 +82,8 @@ function mergeOverlay(base, overlay) {
         credentials: base.credentials,
         allowList: base.allowList,
         platform: base.platform,
-        ...(base.operations ? { operations: base.operations } : {}),
-        ...(base.mcpReads ? { mcpReads: base.mcpReads } : {})
+        operations: base.operations,
+        mcpReads: base.mcpReads
     };
 }
 const OVERLAY_DEFAULT_PLATFORMS = ['darwin', 'linux', 'win32', 'ios', 'android'];
@@ -99,9 +99,11 @@ async function loadRoot(skillsDir, origin) {
     }
     const loaded = await Promise.all(dirs.map((dir) => loadEntry(skillsDir, dir, origin)));
     const byName = new Map();
-    for (const entry of loaded)
-        if (entry)
+    for (const entry of loaded) {
+        if (entry) {
             byName.set(entry.name, entry);
+        }
+    }
     return byName;
 }
 export function mcpReadMethods(catalog) {
@@ -113,11 +115,13 @@ export function mcpReadMethods(catalog) {
             continue;
         for (const url of entry.allowList) {
             const host = hostnameOf(url);
-            if (!host)
+            if (!host) {
                 continue;
+            }
             const methods = byHost.get(host) ?? new Set();
-            for (const method of entry.mcpReads)
+            for (const method of entry.mcpReads) {
                 methods.add(method);
+            }
             byHost.set(host, methods);
         }
     }
@@ -134,6 +138,11 @@ function hostnameOf(url) {
 export function detectPlatform() {
     return platform();
 }
+function platformsOf(declared, origin) {
+    if (declared && declared.length > 0)
+        return declared;
+    return origin === 'overlay' ? OVERLAY_DEFAULT_PLATFORMS : [];
+}
 async function loadEntry(skillsDir, dir, origin) {
     try {
         const skillDir = path.join(skillsDir, dir);
@@ -143,31 +152,27 @@ async function loadEntry(skillsDir, dir, origin) {
         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
-                : [];
+        const platform = platformsOf(meta.platform, origin);
         return {
             name: dir,
             description: meta.description ?? '',
-            ...(meta.aliases ? { aliases: meta.aliases } : {}),
-            ...(meta.preloadOnName === false ? { preloadOnName: false } : {}),
+            aliases: meta.aliases,
+            preloadOnName: meta.preloadOnName === false ? false : undefined,
             tools,
             credentials: meta.credentials ?? [],
             allowList: meta.allowList ?? [],
-            ...(meta.mcpReads ? { mcpReads: 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 } : {})
+            requires: meta.requires,
+            install: meta.install,
+            setup: meta.setup,
+            cliValidator: cli ? buildCliValidator(cli) : undefined,
+            stub: meta.stub,
+            minCapabilityProfile: meta.minCapabilityProfile || undefined,
+            emoji: meta.emoji || undefined,
+            referenceFiles: referenceFiles.length ? referenceFiles : undefined,
+            operations: operations.length ? operations : undefined,
+            origin
         };
     }
     catch {

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

@@ -1,9 +1,10 @@
 import type { JsonSchema } from './cli-schema-types.ts';
-export declare function walkCommands(argv: readonly string[], schema: JsonSchema): {
+export interface CommandWalk {
     node: JsonSchema;
     pathSegs: string[];
     index: number;
-};
+}
+export declare function walkCommands(argv: readonly string[], schema: JsonSchema): CommandWalk;
 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

@@ -4,11 +4,13 @@ export function walkCommands(argv, schema) {
     let i = 0;
     while (i < argv.length) {
         const tok = argv[i] ?? '';
-        if (isParamToken(tok))
+        if (isParamToken(tok)) {
             break;
+        }
         const child = objectProps(node)[tok];
-        if (!child || !isObjectSchema(child))
+        if (!child || !isObjectSchema(child)) {
             break;
+        }
         pathSegs.push(tok);
         node = child;
         i++;
@@ -18,13 +20,10 @@ export function walkCommands(argv, schema) {
 export function argvToObject(argv, schema) {
     const { node, pathSegs, index } = walkCommands(argv, schema);
     const leaf = parseParams(argv.slice(index), node);
-    if (typeof leaf === 'string')
+    if (typeof leaf === 'string') {
         return leaf;
-    let out = leaf;
-    for (let p = pathSegs.length - 1; p >= 0; p--) {
-        out = { [pathSegs[p]]: out };
     }
-    return out;
+    return pathSegs.reduceRight((inner, seg) => ({ [seg]: inner }), leaf);
 }
 export function objectProps(schema) {
     return schema.properties ?? {};
@@ -37,13 +36,25 @@ function isParamToken(tok) {
         return false;
     if (tok.startsWith('-'))
         return true;
-    if (tok.includes('='))
+    if (tok.includes('=')) {
         return true;
+    }
     return false;
 }
+function flagParts(tok) {
+    if (!tok.startsWith('--')) {
+        return { key: tok.slice(1), inline: undefined };
+    }
+    const body = tok.slice(2);
+    const ieq = body.indexOf('=');
+    if (ieq < 0) {
+        return { key: body, inline: undefined };
+    }
+    return { key: body.slice(0, ieq), inline: body.slice(ieq + 1) };
+}
 function parseParams(tokens, schema) {
     const props = objectProps(schema);
-    const propKeys = new Set(Object.keys(props));
+    const propSchemas = new Map(Object.entries(props));
     const boolKeys = new Set(Object.entries(props)
         .filter(([, s]) => s.type === 'boolean')
         .map(([k]) => k));
@@ -59,67 +70,58 @@ function parseParams(tokens, schema) {
         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]);
+            const keySchema = propSchemas.get(key);
+            if (keySchema !== undefined) {
+                out[key] = coerce(tok.slice(eq + 1), keySchema);
                 i++;
                 continue;
             }
-            if (!canAbsorb)
+            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);
+        }
+        const flag = tok.startsWith('-') ? flagParts(tok) : null;
+        const flagSchema = flag ? propSchemas.get(flag.key) : undefined;
+        if (flag && flagSchema !== undefined) {
+            const { key, inline } = flag;
+            if (boolKeys.has(key)) {
+                out[key] = inline !== undefined ? inline !== 'false' && inline !== '0' : true;
+                i++;
+                continue;
             }
-            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;
+            if (inline !== undefined) {
+                out[key] = coerce(inline, flagSchema);
+                i++;
                 continue;
             }
-            if (!canAbsorb)
-                return `unknown flag "--${key}"`;
+            const next = tokens[i + 1];
+            if (next === undefined || next.startsWith('-')) {
+                return `flag --${key} requires a value`;
+            }
+            out[key] = coerce(next, flagSchema);
+            i += 2;
+            continue;
+        }
+        if (flag && !canAbsorb) {
+            return `unknown flag "--${flag.key}"`;
         }
         if (boolKeys.has(tok)) {
             out[tok] = true;
             i++;
             continue;
         }
-        if (propKeys.has(tok) && props[tok]?.type === 'string' && !canAbsorb) {
+        if (propSchemas.get(tok)?.type === 'string' && !canAbsorb) {
             out[tok] = '';
             i++;
             continue;
         }
-        if (posIdx < positionals.length) {
-            const name = positionals[posIdx];
-            if (!propKeys.has(name))
+        const name = positionals[posIdx];
+        if (name !== undefined) {
+            const nameSchema = propSchemas.get(name);
+            if (nameSchema === undefined) {
                 return `x-positionals names unknown property "${name}"`;
-            out[name] = coerce(tok, props[name]);
+            }
+            out[name] = coerce(tok, nameSchema);
             posIdx++;
             i++;
             continue;
@@ -131,8 +133,9 @@ function parseParams(tokens, schema) {
         }
         return `unexpected argument "${tok}"`;
     }
-    if (restName && restVals.length > 0)
+    if (restName && restVals.length > 0) {
         out[restName] = restVals;
+    }
     return out;
 }
 function coerce(value, schema) {