vskill 1.2.4 → 1.2.7

package/dist/commands/audit-webmcp.js

@@ -0,0 +1,167 @@
+/**
+ * vskill audit-webmcp -- audit the WebMCP tools a website registers.
+ *
+ * Loads each URL once in headless Chromium with the WebMCP feature on,
+ * enumerates document.modelContext tools (registerTool capture, CDP WebMCP
+ * domain, getTools), and scores them. Never invokes a tool or submits a form.
+ *
+ * Exit codes: 0 done, 1 a finding at or above --fail-on, 2 bad arguments or
+ * no browser available.
+ */
+import { readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { ArgError, resolveOptions } from "../webmcp/args.js";
+import { enumerateSite, launchBrowser, userAgentFor } from "../webmcp/enumerate.js";
+import { formatBatchFooter, formatSiteTerminal } from "../webmcp/format.js";
+import { atOrAbove, buildReport } from "../webmcp/score.js";
+import { red } from "../utils/output.js";
+/** Scan URLs with a bounded pool; per-site failures become reports with `error`. */
+export async function auditSites(browser, urls, opts, onReport) {
+    const reports = new Array(urls.length);
+    let current = browser;
+    let relaunching = null;
+    const ensureBrowser = async () => {
+        if (current.isConnected() || !opts.relaunch)
+            return;
+        relaunching ??= opts
+            .relaunch()
+            .then((b) => {
+            current = b;
+        })
+            .catch(() => { })
+            .finally(() => {
+            relaunching = null;
+        });
+        await relaunching;
+    };
+    let next = 0;
+    const worker = async () => {
+        while (next < urls.length) {
+            const i = next++;
+            const url = urls[i];
+            await ensureBrowser();
+            const hardLimit = opts.timeoutMs + (opts.settleMs ?? 5000) + 15_000;
+            let timer;
+            // On the hard limit, abort: enumerateSite closes its context so a hung page stops using CPU.
+            const abort = new AbortController();
+            const enumeration = await Promise.race([
+                enumerateSite(current, url, {
+                    timeoutMs: opts.timeoutMs,
+                    settleMs: opts.settleMs,
+                    userAgent: opts.userAgent,
+                    signal: abort.signal,
+                }),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        abort.abort();
+                        reject(new Error(`site scan exceeded ${hardLimit}ms`));
+                    }, hardLimit);
+                }),
+            ])
+                .catch((e) => ({
+                url,
+                finalUrl: null,
+                documentModelContext: false,
+                navigatorModelContext: false,
+                permissionsPolicy: null,
+                tools: [],
+                error: e instanceof Error ? e.message.split("\n")[0] : String(e),
+            }))
+                .finally(() => clearTimeout(timer));
+            const report = buildReport(enumeration);
+            reports[i] = report;
+            onReport?.(report, i);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(opts.concurrency, urls.length)) }, worker));
+    return reports;
+}
+export function shouldFail(reports, failOn) {
+    if (!failOn)
+        return false;
+    return reports.some((r) => r.findings.some((f) => atOrAbove(f.severity, failOn)));
+}
+export async function auditWebmcpCommand(positional, raw) {
+    let opts;
+    try {
+        let fileText;
+        if (raw.urlsFile) {
+            try {
+                fileText = readFileSync(raw.urlsFile, "utf8");
+            }
+            catch (e) {
+                throw new ArgError(`Cannot read --urls-file ${raw.urlsFile}: ${e.message}`);
+            }
+        }
+        opts = resolveOptions(positional, raw, fileText);
+    }
+    catch (e) {
+        if (e instanceof ArgError) {
+            console.error(red(e.message));
+            process.exit(2);
+            return;
+        }
+        throw e;
+    }
+    // Fail on an unwritable --out before starting a browser.
+    if (opts.out) {
+        try {
+            writeFileSync(opts.out, "");
+        }
+        catch (e) {
+            console.error(red(`Cannot write --out ${opts.out}: ${e.message}`));
+            process.exit(2);
+            return;
+        }
+    }
+    let browser;
+    try {
+        browser = await launchBrowser({ executablePath: opts.executablePath });
+    }
+    catch (e) {
+        const err = e;
+        console.error(err.code === "VSKILL_NO_PLAYWRIGHT" ? err.message : red(`Could not launch headless Chromium: ${err.message.split("\n")[0]}`));
+        if (err.code !== "VSKILL_NO_PLAYWRIGHT") {
+            console.error("Install one with `npx playwright install chromium-headless-shell` or pass --executable-path <path>.");
+        }
+        process.exit(2);
+        return;
+    }
+    const batch = opts.urls.length > 1;
+    let reports;
+    try {
+        // Identify the crawler in the UA; fall back to the browser default if that probe fails.
+        const userAgent = await userAgentFor(browser).catch(() => undefined);
+        const relaunch = async () => {
+            await browser.close().catch(() => { });
+            browser = await launchBrowser({ executablePath: opts.executablePath });
+            return browser;
+        };
+        const auditOpts = { concurrency: opts.concurrency, timeoutMs: opts.timeoutMs, userAgent, relaunch };
+        reports = await auditSites(browser, opts.urls, auditOpts, (r, i) => {
+            if (opts.out && opts.outFormat === "jsonl")
+                appendFileSync(opts.out, JSON.stringify(r) + "\n");
+            if (opts.json) {
+                if (batch)
+                    console.log(JSON.stringify(r));
+            }
+            else {
+                if (batch)
+                    process.stderr.write(`[${i + 1}/${opts.urls.length}] ${r.url}\n`);
+                console.log(formatSiteTerminal(r) + "\n");
+            }
+        });
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+    if (opts.out && opts.outFormat === "json")
+        writeFileSync(opts.out, JSON.stringify(reports[0], null, 2) + "\n");
+    if (opts.json && !batch)
+        console.log(JSON.stringify(reports[0], null, 2));
+    if (!opts.json && batch)
+        console.log(formatBatchFooter(reports));
+    // process.exit can drop buffered stdout when it is a pipe (`| jq`): flush first.
+    await new Promise((resolve) => process.stdout.write("", () => resolve()));
+    process.exit(shouldFail(reports, opts.failOn) ? 1 : 0);
+}
+//# sourceMappingURL=audit-webmcp.js.map

package/dist/commands/audit-webmcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-webmcp.js","sourceRoot":"","sources":["../../src/commands/audit-webmcp.ts"],"names":[],"mappings":"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"}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,69 @@
+import { type AgentDefinition } from "../agents/agents-registry.js";
+export type DoctorScope = "global" | "project";
+export type DoctorSeverity = "error" | "warning";
+export type DoctorIssueKind = "divergent" | "identical-copy" | "broken-link" | "redundant-link" | "migration-damage" | "name-mismatch" | "duplicate-name" | "bad-name" | "bad-description";
+export declare const DOCTOR_ISSUE_KINDS: readonly DoctorIssueKind[];
+export interface DoctorIssue {
+    kind: DoctorIssueKind;
+    severity: DoctorSeverity;
+    scope: DoctorScope;
+    /** Skill folder name (or declared name for duplicate-name). */
+    skill: string;
+    /** Every path involved; for identical-copy the first is the kept copy. */
+    paths: string[];
+    message: string;
+    fixable: boolean;
+    /** Agents affected, where it matters (redundant-link, duplicate-name). */
+    agents?: string[];
+}
+export interface DoctorFixAction {
+    kind: DoctorIssueKind;
+    action: "remove-link" | "replace-with-link";
+    path: string;
+    target?: string;
+    ok: boolean;
+    error?: string;
+}
+export interface ScannedDir {
+    scope: DoctorScope;
+    dir: string;
+    readers: string[];
+}
+export interface DoctorReport {
+    scopes: DoctorScope[];
+    scanned: ScannedDir[];
+    issues: DoctorIssue[];
+    fixes: DoctorFixAction[];
+    summary: Record<DoctorIssueKind, number>;
+    /** Problems left after any fixes (equals issues.length). */
+    remaining: number;
+}
+export interface DoctorOptions {
+    global?: boolean;
+    project?: boolean;
+    json?: boolean;
+    fix?: boolean;
+    /** Test seams — default to the real home dir, cwd and platform. */
+    home?: string;
+    cwd?: string;
+    platform?: NodeJS.Platform;
+}
+/** Every dir an agent reads in a scope (absolute paths). */
+export declare function agentSkillDirs(agent: AgentDefinition, scope: DoctorScope, home: string, cwd: string): string[];
+/** Hash every file in a folder (sorted by relative path), ignoring .DS_Store.
+ *  0894: a file's executable bit is part of its record (a copy whose script
+ *  lost +x is not identical), and a symlink inside the skill is hashed by
+ *  where it resolves — inside the skill (relative) or outside (absolute) —
+ *  not by its link text, so `assets -> ../foo-assets` in two copies that
+ *  point at different folders does not count as identical. */
+export declare function hashSkillFolder(dir: string, normalizeSkillMd?: (text: string) => string): string;
+export interface SkillFrontmatter {
+    name?: string;
+    description?: string;
+}
+/** Minimal YAML frontmatter reader for top-level `name` / `description`,
+ *  including folded (`>`) and literal (`|`) block scalars. */
+export declare function parseSkillFrontmatter(content: string): SkillFrontmatter | null;
+/** Run the checks (and fixes when `opts.fix`). Pure apart from `--fix`. */
+export declare function runDoctor(opts?: DoctorOptions): DoctorReport;
+export declare function doctorCommand(opts: DoctorOptions): Promise<void>;