javi-forge 1.26.0 → 1.28.0

package/dist/lib/plugin.js

@@ -4,6 +4,8 @@ import { PLUGIN_ASSET_DIRS, PLUGIN_MANIFEST_FILE, PLUGIN_REGISTRY_URL, PLUGINS_D
 import { generateAgentSkillsManifest } from "./agent-skills.js";
 import { autoWirePlugins } from "./auto-wire.js";
 import { execFileAsync } from "./exec.js";
+import { evaluateInstallGate } from "./skill-install-gate.js";
+import { formatBatchReport, scanSkillsWithCoverage } from "./skill-scanner.js";
 const KEBAB_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const SEMVER_RE = /^\d+\.\d+\.\d+$/;
 // ── Validation ──────────────────────────────────────────────────────────────
@@ -112,7 +114,7 @@ export async function validatePlugin(pluginDir) {
  * Clones the repo to a temp dir, validates, then copies to plugins dir.
  */
 export async function installPlugin(source, options = {}) {
-    const { dryRun = false } = options;
+    const { dryRun = false, force = false } = options;
     // Normalize source to a git URL
     const gitUrl = normalizeGitUrl(source);
     if (!gitUrl) {
@@ -151,6 +153,61 @@ export async function installPlugin(source, options = {}) {
         const pluginName = validation.manifest.name;
         const destDir = path.join(PLUGINS_DIR, pluginName);
         if (!dryRun) {
+            // ── SkillGuard runtime gate (D1/D3, JD-006/JD-007) ────────────
+            // Runs BEFORE the existing-install remove and fs.move: a refusal
+            // leaves staging intact (removed by `finally`) and never destroys a
+            // prior install. dryRun skips the gate entirely (no staged clone).
+            // Scanner/eval errors deny unconditionally (D7 — a throw is not a
+            // verdict, so no force branch consults it).
+            let gate;
+            // Declared results, hoisted for the refusal report: the batch report
+            // renders the FULL declared set (header "Scanned: N" + per-skill rows,
+            // D6) while the lead line still names the rejected count (JD-014).
+            let declaredResults = [];
+            try {
+                const declaredPaths = (validation.manifest.skills ?? []).map((skill) => path.join("skills", skill));
+                const coverage = await scanSkillsWithCoverage(tmpDir, declaredPaths);
+                // Manifest-integrity refusals — block-level, force NEVER lifts
+                // (JD-007: ANY symlink; JD-006: undeclared SKILL.md incl.
+                // node_modules/.git). A walk with I/O errors cannot certify the
+                // installed footprint — refuse first, before symlink/undeclared
+                // checks, because the broken subtree may hide either (JD-013).
+                if (coverage.errors.length > 0) {
+                    return {
+                        success: false,
+                        error: `skillguard: install refused — ${coverage.errors.length} path(s) could not be read (walk incomplete; manifest-integrity, force never lifts):\n${coverage.errors.map((p) => `  ${p}`).join("\n")}`,
+                    };
+                }
+                if (coverage.symlinks.length > 0) {
+                    return {
+                        success: false,
+                        error: `skillguard: install refused — symlink(s) in tree (manifest-integrity, force never lifts):\n${coverage.symlinks.map((p) => `  ${p}`).join("\n")}`,
+                    };
+                }
+                if (coverage.undeclared.length > 0) {
+                    return {
+                        success: false,
+                        error: `skillguard: install refused — undeclared SKILL.md(s) in tree (every skill-shaped file must be declared; force never lifts):\n${coverage.undeclared.map((p) => `  ${p}`).join("\n")}`,
+                    };
+                }
+                declaredResults = coverage.declared;
+                gate = evaluateInstallGate(coverage.declared, { force });
+            }
+            catch (scanError) {
+                const msg = scanError instanceof Error ? scanError.message : String(scanError);
+                return {
+                    success: false,
+                    error: `skillguard scan failed — ${msg}`,
+                };
+            }
+            if (!gate.allowed) {
+                const blocked = gate.rejected.filter((r) => r.verdict === "block").length;
+                const unscannable = gate.rejected.filter((r) => r.verdict === "unscannable").length;
+                return {
+                    success: false,
+                    error: `skillguard: install refused — ${gate.rejected.length} rejected (${blocked} blocked, ${unscannable} unscannable)\n${formatBatchReport(declaredResults)}`,
+                };
+            }
             // Remove existing version if present
             if (await fs.pathExists(destDir)) {
                 await fs.remove(destDir);

package/dist/lib/safe-read.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Bounded, non-throwing file reads.
+ *
+ * Every whole-file read in this CLI used to be an unguarded
+ * `fs.readFile(path, "utf-8")`: a 400 MB log, a minified bundle or a binary
+ * blob under a scanned directory could exhaust memory or stall a scan. This
+ * module is the single guarded entry point — it caps bytes during the read,
+ * rejects binaries by content sniffing, clamps pathological single lines, and
+ * returns a discriminated union instead of throwing for expected conditions.
+ *
+ * Deliberately NOT included: no path allow/block list. This is a local CLI
+ * operating on the user's own repository, so any path they can name they can
+ * already `cat`; a blocklist would add friction without adding a boundary.
+ */
+/** Default byte budget for a single read (1 MiB). */
+export declare const DEFAULT_MAX_BYTES: number;
+/** Default per-line character clamp — catches minified bundles and data URIs. */
+export declare const DEFAULT_MAX_LINE_LENGTH = 10000;
+export interface SafeReadOptions {
+    /** Maximum bytes kept. Anything beyond is dropped and `truncated` is set. */
+    maxBytes?: number;
+    /** Per-line character clamp. Use `0` or `Infinity` to disable. */
+    maxLineLength?: number;
+    /**
+     * If the file is larger than this, fail with `too-large` instead of
+     * truncating. Off by default — truncation is the normal behavior.
+     */
+    hardRejectOverBytes?: number;
+}
+export type SafeReadFailureReason = "not-found" | "not-a-file" | "binary" | "too-large" | "io-error";
+export interface SafeReadSuccess {
+    ok: true;
+    content: string;
+    /** True when the file had more bytes than the budget allowed. */
+    truncated: boolean;
+    /** Bytes actually decoded into `content` (before BOM stripping). */
+    bytesRead: number;
+    /** File size reported by `stat` at the time of the read. */
+    totalBytes: number;
+    /** True when at least one line hit the per-line clamp. */
+    longLinesClamped: boolean;
+}
+export interface SafeReadFailure {
+    ok: false;
+    reason: SafeReadFailureReason;
+    detail?: string;
+}
+export type SafeReadResult = SafeReadSuccess | SafeReadFailure;
+/**
+ * Read a text file with a byte budget, binary rejection and line clamping.
+ *
+ * Never throws for expected conditions (missing file, directory, binary,
+ * oversized, permission denied) — inspect `result.ok` and branch on `reason`.
+ *
+ * Newlines are returned verbatim: CRLF is NOT normalized, because the callers
+ * migrated to this helper already tolerate `\r` (they `trim()` split lines) and
+ * silently rewriting bytes would make reported offsets diverge from the file.
+ */
+export declare function safeReadFile(filePath: string, opts?: SafeReadOptions): Promise<SafeReadResult>;
+/** Human-readable one-liner for a failed read — for CLI notes and findings. */
+export declare function describeSafeReadFailure(failure: SafeReadFailure): string;
+//# sourceMappingURL=safe-read.d.ts.map

package/dist/lib/safe-read.js

@@ -0,0 +1,221 @@
+/**
+ * Bounded, non-throwing file reads.
+ *
+ * Every whole-file read in this CLI used to be an unguarded
+ * `fs.readFile(path, "utf-8")`: a 400 MB log, a minified bundle or a binary
+ * blob under a scanned directory could exhaust memory or stall a scan. This
+ * module is the single guarded entry point — it caps bytes during the read,
+ * rejects binaries by content sniffing, clamps pathological single lines, and
+ * returns a discriminated union instead of throwing for expected conditions.
+ *
+ * Deliberately NOT included: no path allow/block list. This is a local CLI
+ * operating on the user's own repository, so any path they can name they can
+ * already `cat`; a blocklist would add friction without adding a boundary.
+ */
+import { open, stat } from "node:fs/promises";
+// =============================================================================
+// Constants
+// =============================================================================
+/** Default byte budget for a single read (1 MiB). */
+export const DEFAULT_MAX_BYTES = 1024 * 1024;
+/** Default per-line character clamp — catches minified bundles and data URIs. */
+export const DEFAULT_MAX_LINE_LENGTH = 10_000;
+/** Size of each read from the file handle. */
+const READ_CHUNK_BYTES = 64 * 1024;
+/** Bytes of the first chunk sniffed for NUL when classifying binary content. */
+const BINARY_SNIFF_BYTES = 8 * 1024;
+const BOM = "\uFEFF";
+// =============================================================================
+// Internal helpers
+// =============================================================================
+function errnoOf(err) {
+    return typeof err === "object" && err !== null && "code" in err
+        ? String(err.code)
+        : undefined;
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Drop a trailing partial UTF-8 sequence so a byte-capped buffer never decodes
+ * into a replacement character. Scans back at most 3 bytes (max lead distance
+ * for a 4-byte sequence) looking for a lead byte whose sequence would run past
+ * the end of the buffer.
+ */
+function trimPartialUtf8(buf) {
+    const maxLookback = Math.min(3, buf.length);
+    for (let back = 0; back < maxLookback; back++) {
+        const index = buf.length - 1 - back;
+        const byte = buf[index];
+        // Continuation byte (10xxxxxx): keep walking back to its lead byte.
+        if ((byte & 0xc0) === 0x80)
+            continue;
+        // ASCII byte: the buffer ends on a complete codepoint.
+        if ((byte & 0x80) === 0)
+            return buf;
+        // Lead byte: does its full sequence fit in what we kept?
+        let needed = 0;
+        if ((byte & 0xe0) === 0xc0)
+            needed = 2;
+        else if ((byte & 0xf0) === 0xe0)
+            needed = 3;
+        else if ((byte & 0xf8) === 0xf0)
+            needed = 4;
+        else
+            return buf; // invalid lead byte — leave it to the decoder
+        const available = buf.length - index;
+        return available >= needed ? buf : buf.subarray(0, index);
+    }
+    return buf;
+}
+/** Clamp lines longer than `maxLineLength`, marking how much was dropped. */
+function clampLongLines(content, maxLineLength) {
+    if (!Number.isFinite(maxLineLength) || maxLineLength <= 0) {
+        return { content, clamped: false };
+    }
+    if (content.length <= maxLineLength)
+        return { content, clamped: false };
+    const lines = content.split("\n");
+    let clamped = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.length <= maxLineLength)
+            continue;
+        const dropped = line.length - maxLineLength;
+        lines[i] = `${line.slice(0, maxLineLength)}…[clamped ${dropped} chars]`;
+        clamped = true;
+    }
+    return clamped
+        ? { content: lines.join("\n"), clamped }
+        : { content, clamped };
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Read a text file with a byte budget, binary rejection and line clamping.
+ *
+ * Never throws for expected conditions (missing file, directory, binary,
+ * oversized, permission denied) — inspect `result.ok` and branch on `reason`.
+ *
+ * Newlines are returned verbatim: CRLF is NOT normalized, because the callers
+ * migrated to this helper already tolerate `\r` (they `trim()` split lines) and
+ * silently rewriting bytes would make reported offsets diverge from the file.
+ */
+export async function safeReadFile(filePath, opts = {}) {
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+    const maxLineLength = opts.maxLineLength ?? DEFAULT_MAX_LINE_LENGTH;
+    const hardRejectOverBytes = opts.hardRejectOverBytes;
+    // -- Stat first: classify directories, sockets and missing paths cheaply ---
+    let totalBytes;
+    try {
+        const stats = await stat(filePath);
+        if (!stats.isFile()) {
+            return {
+                ok: false,
+                reason: "not-a-file",
+                detail: stats.isDirectory()
+                    ? "path is a directory"
+                    : "not a regular file",
+            };
+        }
+        totalBytes = stats.size;
+    }
+    catch (err) {
+        const code = errnoOf(err);
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            return { ok: false, reason: "not-found", detail: filePath };
+        }
+        return { ok: false, reason: "io-error", detail: messageOf(err) };
+    }
+    if (hardRejectOverBytes !== undefined && totalBytes > hardRejectOverBytes) {
+        return {
+            ok: false,
+            reason: "too-large",
+            detail: `${totalBytes} bytes exceeds limit of ${hardRejectOverBytes}`,
+        };
+    }
+    if (maxBytes <= 0) {
+        return {
+            ok: true,
+            content: "",
+            truncated: totalBytes > 0,
+            bytesRead: 0,
+            totalBytes,
+            longLinesClamped: false,
+        };
+    }
+    // -- Read in chunks, enforcing the budget as we go (never buffer it all) ---
+    const chunks = [];
+    let collected = 0;
+    let truncated = false;
+    let handle;
+    try {
+        handle = await open(filePath, "r");
+        while (collected < maxBytes) {
+            const want = Math.min(READ_CHUNK_BYTES, maxBytes - collected);
+            const buf = Buffer.allocUnsafe(want);
+            const { bytesRead } = await handle.read(buf, 0, want, null);
+            if (bytesRead === 0)
+                break;
+            const chunk = buf.subarray(0, bytesRead);
+            // Binary sniff on the first chunk only — by content, never extension.
+            if (chunks.length === 0) {
+                const sniff = chunk.subarray(0, BINARY_SNIFF_BYTES);
+                if (sniff.includes(0)) {
+                    return {
+                        ok: false,
+                        reason: "binary",
+                        detail: "NUL byte in first chunk",
+                    };
+                }
+            }
+            chunks.push(chunk);
+            collected += bytesRead;
+        }
+        // One probe byte tells us whether the budget actually cut something off.
+        if (collected >= maxBytes) {
+            const probe = Buffer.allocUnsafe(1);
+            const { bytesRead } = await handle.read(probe, 0, 1, null);
+            truncated = bytesRead > 0;
+        }
+    }
+    catch (err) {
+        return { ok: false, reason: "io-error", detail: messageOf(err) };
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+    let buffer = Buffer.concat(chunks, collected);
+    if (truncated)
+        buffer = trimPartialUtf8(buffer);
+    const bytesRead = buffer.length;
+    let content = buffer.toString("utf-8");
+    if (content.startsWith(BOM))
+        content = content.slice(BOM.length);
+    const { content: clampedContent, clamped } = clampLongLines(content, maxLineLength);
+    return {
+        ok: true,
+        content: clampedContent,
+        truncated,
+        bytesRead,
+        totalBytes,
+        longLinesClamped: clamped,
+    };
+}
+/** Human-readable one-liner for a failed read — for CLI notes and findings. */
+export function describeSafeReadFailure(failure) {
+    switch (failure.reason) {
+        case "not-found":
+            return "file not found";
+        case "not-a-file":
+            return failure.detail ?? "not a regular file";
+        case "binary":
+            return "binary file";
+        case "too-large":
+            return failure.detail ? `too large (${failure.detail})` : "too large";
+        case "io-error":
+            return failure.detail ? `read error: ${failure.detail}` : "read error";
+    }
+}
+//# sourceMappingURL=safe-read.js.map

package/dist/lib/security-analysis.d.ts

@@ -25,12 +25,29 @@ export interface SecurityAnalysisReport {
     projectDir: string;
     findings: SecurityAnalysisFinding[];
     summary: SecurityAnalysisSummary;
+    /**
+     * Files the pattern pass never saw — binary, oversized or unreadable. A scan
+     * that silently skipped files is not a clean scan, so they are reported.
+     */
+    skipped?: SecurityAnalysisSkippedFile[];
+}
+export interface SecurityAnalysisSkippedFile {
+    /** Path relative to `projectDir`, matching the finding paths. */
+    file: string;
+    reason: string;
 }
 export interface SecurityAnalysisSummary {
     total: number;
     bySeverity: Record<SecuritySeverity, number>;
     byCategory: Record<string, number>;
     passed: boolean;
+    /**
+     * True when at least one file was skipped or only partially scanned (binary,
+     * oversized, I/O error, truncated, or clamped). The scan did not see the whole
+     * codebase, so `passed` is forced to `false` — a clean result over an
+     * incomplete scan would be a fail-open lie.
+     */
+    incomplete: boolean;
     failThreshold: SecuritySeverity;
 }
 export interface SecurityAnalysisOptions {
@@ -64,8 +81,8 @@ export declare function detectFileLanguage(filePath: string): string | null;
 export declare function matchRule(rule: SemgrepRule, content: string, filePath: string): SecurityAnalysisFinding[];
 export declare function collectFiles(dir: string): Promise<string[]>;
 export declare function severityAtOrAbove(severity: SecuritySeverity, threshold: SecuritySeverity): boolean;
-export declare function buildSummary(findings: SecurityAnalysisFinding[], failThreshold: SecuritySeverity): SecurityAnalysisSummary;
-export declare function buildReport(findings: SecurityAnalysisFinding[], projectDir: string, options?: SecurityAnalysisOptions): SecurityAnalysisReport;
+export declare function buildSummary(findings: SecurityAnalysisFinding[], failThreshold: SecuritySeverity, incomplete?: boolean): SecurityAnalysisSummary;
+export declare function buildReport(findings: SecurityAnalysisFinding[], projectDir: string, options?: SecurityAnalysisOptions, skipped?: SecurityAnalysisSkippedFile[]): SecurityAnalysisReport;
 export declare function filterRules(rules: SemgrepRule[], options?: SecurityAnalysisOptions): SemgrepRule[];
 export declare function loadCustomRules(rulesDir: string): Promise<SemgrepRule[]>;
 export declare function runSecurityAnalysis(projectDir: string, options?: SecurityAnalysisOptions): Promise<SecurityAnalysisReport>;

package/dist/lib/security-analysis.js

@@ -7,9 +7,15 @@
  */
 import path from "node:path";
 import fs from "fs-extra";
+import { describeSafeReadFailure, safeReadFile } from "./safe-read.js";
 // =============================================================================
 // Constants
 // =============================================================================
+/**
+ * Hard ceiling per scanned file. Source files past this are generated or
+ * vendored bundles: running every rule over them costs far more than it finds.
+ */
+const MAX_ANALYSIS_BYTES = 2 * 1024 * 1024;
 const SEVERITY_ORDER = {
     critical: 5,
     high: 4,
@@ -316,7 +322,7 @@ export function severityAtOrAbove(severity, threshold) {
 // =============================================================================
 // Report generation
 // =============================================================================
-export function buildSummary(findings, failThreshold) {
+export function buildSummary(findings, failThreshold, incomplete = false) {
     const bySeverity = {
         critical: 0,
         high: 0,
@@ -329,23 +335,29 @@ export function buildSummary(findings, failThreshold) {
         bySeverity[f.severity]++;
         byCategory[f.category] = (byCategory[f.category] ?? 0) + 1;
     }
-    const passed = !findings.some((f) => severityAtOrAbove(f.severity, failThreshold));
+    // Fail closed on an incomplete scan: a file we never fully read could hold the
+    // very finding that would have failed the gate. No threshold finding is not
+    // the same as "clean" when part of the codebase was invisible to the scan.
+    const noThresholdFinding = !findings.some((f) => severityAtOrAbove(f.severity, failThreshold));
+    const passed = noThresholdFinding && !incomplete;
     return {
         total: findings.length,
         bySeverity,
         byCategory,
         passed,
+        incomplete,
         failThreshold,
     };
 }
-export function buildReport(findings, projectDir, options = {}) {
+export function buildReport(findings, projectDir, options = {}, skipped = []) {
     const failThreshold = options.failThreshold ?? "high";
     return {
         engine: "semgrep",
         timestamp: new Date().toISOString(),
         projectDir,
         findings,
-        summary: buildSummary(findings, failThreshold),
+        summary: buildSummary(findings, failThreshold, skipped.length > 0),
+        ...(skipped.length > 0 ? { skipped } : {}),
     };
 }
 // =============================================================================
@@ -426,16 +438,42 @@ export async function runSecurityAnalysis(projectDir, options = {}) {
     }
     // Run pattern matching
     const findings = [];
+    const skipped = [];
     for (const filePath of allFiles) {
-        let content;
-        try {
-            content = await fs.readFile(filePath, "utf-8");
-        }
-        catch {
-            continue;
-        }
+        // Guarded read: a binary blob or a multi-megabyte bundle would otherwise
+        // be fed to every regex rule in the set. `maxBytes` is pinned to the same
+        // ceiling as the hard reject so the documented 2 MiB limit is the effective
+        // scan cap — otherwise the 1 MiB default would silently truncate every file
+        // between 1 and 2 MiB and MAX_ANALYSIS_BYTES would be a dead constant.
+        const read = await safeReadFile(filePath, {
+            maxBytes: MAX_ANALYSIS_BYTES,
+            hardRejectOverBytes: MAX_ANALYSIS_BYTES,
+        });
         // Use relative paths in findings for readability
         const relativePath = path.relative(projectDir, filePath);
+        if (!read.ok) {
+            skipped.push({
+                file: relativePath,
+                reason: describeSafeReadFailure(read),
+            });
+            continue;
+        }
+        const content = read.content;
+        if (read.truncated) {
+            skipped.push({
+                file: relativePath,
+                reason: `truncated at ${read.bytesRead} of ${read.totalBytes} bytes — scanned partially`,
+            });
+        }
+        // A clamped long line means the regex pass saw a shortened line — a payload
+        // hidden past the clamp would be invisible. Record it like a truncation so
+        // the scan is marked incomplete and cannot report a clean pass.
+        if (read.longLinesClamped) {
+            skipped.push({
+                file: relativePath,
+                reason: "long line(s) clamped — scanned partially",
+            });
+        }
         for (const rule of rules) {
             const matches = matchRule(rule, content, filePath);
             // Rewrite file paths to relative
@@ -452,7 +490,7 @@ export async function runSecurityAnalysis(projectDir, options = {}) {
             return sevDiff;
         return a.file.localeCompare(b.file);
     });
-    return buildReport(findings, projectDir, options);
+    return buildReport(findings, projectDir, options, skipped);
 }
 // =============================================================================
 // Report formatting (for CI output)
@@ -468,7 +506,14 @@ export function formatReportText(report) {
         .map(([sev, count]) => `${count} ${sev}`)
         .join(", ") || "none"}`);
     lines.push(`Pass threshold: ${summary.failThreshold}`);
-    lines.push(`Result: ${summary.passed ? "PASS" : "FAIL"}`);
+    lines.push(`Result: ${summary.passed
+        ? "PASS"
+        : summary.incomplete
+            ? "FAIL (incomplete scan — some files were not fully analysed)"
+            : "FAIL"}`);
+    if (report.skipped && report.skipped.length > 0) {
+        lines.push(`Skipped files: ${report.skipped.length}`);
+    }
     lines.push("");
     if (findings.length > 0) {
         lines.push("--- Findings ---");
@@ -481,6 +526,13 @@ export function formatReportText(report) {
             lines.push(`  ${f.message}`);
         }
     }
+    if (report.skipped && report.skipped.length > 0) {
+        lines.push("");
+        lines.push("--- Skipped ---");
+        for (const s of report.skipped) {
+            lines.push(`${s.file}: ${s.reason}`);
+        }
+    }
     return lines.join("\n");
 }
 export function formatReportJson(report) {

package/dist/lib/skill-install-gate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared install-gate evaluation for the skillguard runtime gate (D2).
+ *
+ * Pure helper: verdict evaluation for a set of declared skill scans lives in
+ * exactly one place so all three entrypoints (plugin add, plugin import, skills
+ * auto-install) share identical force semantics. Scanning + try/catch stay at
+ * the call sites (a pure helper cannot own the I/O); this module imports no fs.
+ *
+ * Force rule (fail-closed): `block` always refuses; `--force` lifts ONLY
+ * `unscannable`. Manifest-integrity refusals (undeclared SKILL.md in the tree,
+ * any symlink, empty/missing `skills` on import, declared paths escaping the
+ * source dir) are NOT verdicts — call sites enforce them BEFORE this helper
+ * runs, so `force` can never lift them either.
+ */
+import type { SkillScanResult } from "./skill-scanner.js";
+export interface InstallGateDecision {
+    allowed: boolean;
+    /** Rejected results when `!allowed`, else `[]`. */
+    rejected: SkillScanResult[];
+}
+/**
+ * Evaluate a set of declared-skill scan results against the install gate.
+ *
+ * `allowed = !hasBlock && (rejected.length === 0 || force)` — a `block` verdict
+ * refuses unconditionally; `force` bypasses ONLY `unscannable`. Empty,
+ * pass, and warn results are allowed.
+ */
+export declare function evaluateInstallGate(results: SkillScanResult[], options?: {
+    force?: boolean;
+}): InstallGateDecision;
+//# sourceMappingURL=skill-install-gate.d.ts.map

package/dist/lib/skill-install-gate.js

@@ -0,0 +1,30 @@
+/**
+ * Shared install-gate evaluation for the skillguard runtime gate (D2).
+ *
+ * Pure helper: verdict evaluation for a set of declared skill scans lives in
+ * exactly one place so all three entrypoints (plugin add, plugin import, skills
+ * auto-install) share identical force semantics. Scanning + try/catch stay at
+ * the call sites (a pure helper cannot own the I/O); this module imports no fs.
+ *
+ * Force rule (fail-closed): `block` always refuses; `--force` lifts ONLY
+ * `unscannable`. Manifest-integrity refusals (undeclared SKILL.md in the tree,
+ * any symlink, empty/missing `skills` on import, declared paths escaping the
+ * source dir) are NOT verdicts — call sites enforce them BEFORE this helper
+ * runs, so `force` can never lift them either.
+ */
+import { isRejectedVerdict } from "./skill-scanner.js";
+/**
+ * Evaluate a set of declared-skill scan results against the install gate.
+ *
+ * `allowed = !hasBlock && (rejected.length === 0 || force)` — a `block` verdict
+ * refuses unconditionally; `force` bypasses ONLY `unscannable`. Empty,
+ * pass, and warn results are allowed.
+ */
+export function evaluateInstallGate(results, options) {
+    const rejected = results.filter((r) => isRejectedVerdict(r.verdict));
+    const hasBlock = results.some((r) => r.verdict === "block");
+    const force = options?.force ?? false;
+    const allowed = !hasBlock && (rejected.length === 0 || force);
+    return { allowed, rejected: allowed ? [] : rejected };
+}
+//# sourceMappingURL=skill-install-gate.js.map