javi-forge 1.26.0 → 1.27.0

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-scanner.d.ts

@@ -15,13 +15,34 @@ export interface SkillThreat {
     context: string;
     message: string;
 }
-export type SkillScanVerdict = "pass" | "warn" | "block";
+/**
+ * `unscannable` is a fail-closed verdict: the file could not be read in full
+ * (binary, oversized, I/O error) or a content-mutating clamp/truncation
+ * happened during the read, so we cannot certify it. A gate MUST treat it as a
+ * rejection exactly like `block` — see {@link isRejectedVerdict}, the single
+ * predicate every install/registry gate should use instead of `=== "block"`.
+ */
+export type SkillScanVerdict = "pass" | "warn" | "block" | "unscannable";
+/**
+ * The set of verdicts an install/registry gate rejects on. Fail-closed:
+ * `block` (a critical threat was found) and `unscannable` (the file could not
+ * be certified because it was not fully scanned) both mean "do not install".
+ * Use this everywhere instead of a bare `verdict === "block"` check so a future
+ * gate can never let an `unscannable` file slip through.
+ */
+export declare function isRejectedVerdict(verdict: SkillScanVerdict): boolean;
 export interface SkillScanResult {
     skillPath: string;
     skillName: string;
     verdict: SkillScanVerdict;
     threats: SkillThreat[];
     summary: SkillScanSummary;
+    /**
+     * Scan-level notes — populated when the file could not be fully analysed
+     * (binary, oversized, unreadable) so a skipped file is visible in the report
+     * instead of masquerading as a clean pass.
+     */
+    notes?: string[];
 }
 export interface SkillScanSummary {
     total: number;

package/dist/lib/skill-scanner.js

@@ -7,6 +7,17 @@
  */
 import path from "node:path";
 import fs from "fs-extra";
+import { describeSafeReadFailure, safeReadFile } from "./safe-read.js";
+/**
+ * The set of verdicts an install/registry gate rejects on. Fail-closed:
+ * `block` (a critical threat was found) and `unscannable` (the file could not
+ * be certified because it was not fully scanned) both mean "do not install".
+ * Use this everywhere instead of a bare `verdict === "block"` check so a future
+ * gate can never let an `unscannable` file slip through.
+ */
+export function isRejectedVerdict(verdict) {
+    return verdict === "block" || verdict === "unscannable";
+}
 /**
  * Ordered by severity (critical first). Each pattern is tested against
  * every non-comment line in the skill file.
@@ -282,18 +293,66 @@ export function extractSkillName(content, filePath) {
 // =============================================================================
 // Main scan function
 // =============================================================================
+/**
+ * Hard ceiling for a scanned skill file. Past this it is not a skill document
+ * but a dumped log or a vendored bundle: scanning it would run every regex
+ * over megabytes of noise, so it is skipped and reported instead.
+ */
+const MAX_SCAN_BYTES = 1024 * 1024;
 export async function scanSkillFile(filePath) {
-    const content = await fs.readFile(filePath, "utf-8");
+    // `maxLineLength: 0` disables the per-line clamp for the scanner's own read:
+    // a padded single line hiding `rm -rf ~` past column 10k must reach the regex
+    // pass intact, not be silently truncated and then scanned as if complete. The
+    // total-byte ceiling still bounds memory (a file past it fails `too-large`).
+    const read = await safeReadFile(filePath, {
+        hardRejectOverBytes: MAX_SCAN_BYTES,
+        maxLineLength: 0,
+    });
+    // A file we could not read is not a clean file. Never crash the batch, and
+    // never report it as a pass: an unscannable file cannot be certified safe, so
+    // it fails closed with the strongest verdict a gate rejects on.
+    if (!read.ok) {
+        return {
+            skillPath: filePath,
+            skillName: path.basename(path.dirname(filePath)),
+            verdict: "unscannable",
+            threats: [],
+            summary: computeScanSummary([]),
+            notes: [
+                `scanning incomplete: ${describeSafeReadFailure(read)} — rejected (an unscannable file cannot be certified safe)`,
+            ],
+        };
+    }
+    const content = read.content;
     const skillName = extractSkillName(content, filePath);
     const threats = scanSkillContent(content, filePath);
-    const verdict = computeVerdict(threats);
     const summary = computeScanSummary(threats);
+    // A content-mutating read (truncated bytes, or a clamped line) means the
+    // regex pass did NOT see the whole file. Even if no threat surfaced in what
+    // we did see, we cannot certify the rest — fail closed rather than emit a
+    // pass/warn over partial content. With `maxLineLength: 0` and the byte
+    // ceiling above these should not fire, but the guard is the safety net.
+    const incomplete = read.truncated || read.longLinesClamped;
+    const notes = [];
+    if (read.truncated) {
+        notes.push(`truncated: only the first ${read.bytesRead} of ${read.totalBytes} bytes were scanned`);
+    }
+    if (read.longLinesClamped) {
+        notes.push("clamped: one or more lines exceeded the per-line limit");
+    }
+    if (incomplete) {
+        notes.push("rejected: the file was not fully scanned and cannot be certified safe");
+    }
+    const verdict = incomplete
+        ? "unscannable"
+        : computeVerdict(threats);
     return {
         skillPath: filePath,
         skillName,
         verdict,
         threats,
         summary,
+        ...(notes.length > 0 ? { notes } : {}),
     };
 }
 /**
@@ -346,6 +405,12 @@ export function formatScanReport(result) {
     lines.push(`Verdict: ${verdict.toUpperCase()}`);
     lines.push(`Findings: ${summary.total} (${summary.critical} critical, ${summary.high} high, ${summary.moderate} moderate, ${summary.low} low)`);
     lines.push("");
+    if (result.notes && result.notes.length > 0) {
+        lines.push("--- Notes ---");
+        for (const note of result.notes)
+            lines.push(`  ${note}`);
+        lines.push("");
+    }
     if (threats.length > 0) {
         lines.push("--- Threats ---");
         for (const t of threats) {
@@ -354,7 +419,11 @@ export function formatScanReport(result) {
             lines.push(`  Context: ${t.context}`);
         }
     }
-    if (verdict === "block") {
+    if (verdict === "unscannable") {
+        lines.push("");
+        lines.push("REJECTED: File could not be fully scanned, so it cannot be certified safe. Not installed.");
+    }
+    else if (verdict === "block") {
         lines.push("");
         lines.push("BLOCKED: Critical threats detected. Review and remove before installing.");
     }
@@ -367,11 +436,14 @@ export function formatScanReport(result) {
 export function formatBatchReport(results) {
     const lines = [];
     const blocked = results.filter((r) => r.verdict === "block");
+    const unscannable = results.filter((r) => r.verdict === "unscannable");
     const warned = results.filter((r) => r.verdict === "warn");
     const passed = results.filter((r) => r.verdict === "pass");
     lines.push(`=== SkillGuard Batch Scan ===`);
     lines.push(`Scanned: ${results.length} skill(s)`);
-    lines.push(`Blocked: ${blocked.length}`);
+    lines.push(`Rejected: ${blocked.length + unscannable.length}`);
+    lines.push(`  Blocked (threats): ${blocked.length}`);
+    lines.push(`  Unscannable (not certified): ${unscannable.length}`);
     lines.push(`Warned: ${warned.length}`);
     lines.push(`Passed: ${passed.length}`);
     lines.push("");

package/dist/types/index.d.ts

@@ -226,6 +226,11 @@ export interface SkillBudgetEntry {
     skillName: string;
     skillPath: string;
     tokens: number;
+    /**
+     * Set when the SKILL.md could not be fully read (binary, oversized, I/O
+     * error) — `tokens` is then partial or zero and should be read with care.
+     */
+    note?: string;
 }
 export interface SkillBudgetSuggestion {
     /** Skills to disable in this suggestion set */
@@ -271,6 +276,13 @@ export interface SkillScore {
     grade: SkillGrade;
     threshold: number;
     passing: boolean;
+    /**
+     * Set when the SKILL.md could not be read (binary, oversized, I/O error). The
+     * numeric dimensions are then meaningless placeholders (all `0`, never a
+     * computed grade or `safety: 100`); callers must surface the file as unread
+     * rather than as a scored skill. `passing` is always `false` in this state.
+     */
+    unread?: string;
 }
 export interface SkillRegistryGateResult {
     skillName: string;
@@ -287,6 +299,12 @@ export interface SkillBenchmarkResult {
     skillName: string;
     checks: SkillBenchmarkCheck[];
     passRate: number;
+    /**
+     * Set when the SKILL.md could not be read (binary, oversized, I/O error). No
+     * checks were run (`checks` is empty, `passRate` is `0`); callers must surface
+     * the file as unread rather than as a benchmarked skill that failed every check.
+     */
+    unread?: string;
 }
 declare const WORKFLOW_FORMAT: {
     readonly DOT: "dot";

package/dist/ui/Skills.js

@@ -66,13 +66,18 @@ export default function Skills({ mode, budget, deep, skillsDir }) {
                         result.budget.budget,
                         " tokens",
                         result.budget.overBudget ? " (OVER BUDGET)" : "")),
-                result.budget.entries.map((entry) => (React.createElement(Box, { key: entry.skillName, marginLeft: 4 },
-                    React.createElement(Text, { color: theme.muted }, entry.skillName),
-                    React.createElement(Text, { color: theme.muted, dimColor: true },
-                        "  ",
-                        "~",
-                        entry.tokens,
-                        " tokens")))),
+                result.budget.entries.map((entry) => (React.createElement(Box, { key: entry.skillName, flexDirection: "column", marginLeft: 4 },
+                    React.createElement(Box, null,
+                        React.createElement(Text, { color: entry.note ? theme.warning : theme.muted }, entry.skillName),
+                        React.createElement(Text, { color: theme.muted, dimColor: true },
+                            "  ",
+                            "~",
+                            entry.tokens,
+                            " tokens")),
+                    entry.note && (React.createElement(Box, { marginLeft: 2 },
+                        React.createElement(Text, { color: theme.warning },
+                            "! ",
+                            entry.note)))))),
                 result.budget.suggestions.map((s, i) => (React.createElement(Box, { key: `suggestion-${i}`, marginLeft: 4 },
                     React.createElement(Text, { color: theme.warning },
                         "! ",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "javi-forge",
-	"version": "1.26.0",
+	"version": "1.27.0",
 	"description": "Project scaffolding and AI-ready CI bootstrap",
 	"type": "module",
 	"bin": {

package/templates/github/ghagga-review.yml

@@ -1,30 +0,0 @@
-# ===========================================
-# GHAGGA AI Code Review
-# ===========================================
-# Triggers AI code review on pull requests.
-# Requires: GHAGGA GitHub Action (JNZader/ghagga@v1)
-#
-# Modes: simple (default), workflow, consensus
-# ===========================================
-
-name: Code Review
-
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-
-permissions:
-  pull-requests: write
-  contents: read
-
-jobs:
-  review:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
-      # TODO(pin): ghagga has no v1 tag upstream (releases start at v2) — this
-      # ref cannot be SHA-pinned as-is; pick a real released tag and pin it.
-      - uses: JNZader/ghagga@v1
-        with:
-          mode: simple
-          provider: github