javi-forge 1.25.1 → 1.27.0

package/dist/commands/hooks/sections/secrets.js

@@ -0,0 +1,182 @@
+/**
+ * L1 secret-scan section (hook-consolidation S4).
+ *
+ * Port of `templates/security-hooks/pre-commit-secrets` into TypeScript. The
+ * bash body built the staged-file list with `git diff --cached --name-only`
+ * and then piped it through `xargs git diff` (pre-commit-secrets:52) — a
+ * whitespace split that silently dropped any path containing a space and
+ * swallowed the git error with `|| true` (K-005). This port builds the staged
+ * list NUL-safe (`-z` → split on `"\0"`) and passes each filename as a SEPARATE
+ * argv element to `git diff` (no shell, no xargs), so a path like
+ * `app secrets.env` is scanned as ONE path and can never be split.
+ *
+ * A matched pattern in an ADDED diff line blocks the commit (ok:false).
+ */
+import { execFileAsync } from "../../../lib/exec.js";
+/**
+ * Ported from `templates/security-hooks/pre-commit-secrets` SECRET_PATTERNS.
+ * bash `(?i)` → the JS `/i` flag; bash `\x27` (a single quote) → a literal `'`.
+ * No `/g` flag is used, so `.test()` never carries `lastIndex` state between
+ * lines. Order is preserved from the bash array.
+ */
+const SECRET_PATTERNS = [
+    // AWS access key id
+    { name: "aws-access-key", re: /AKIA[0-9A-Z]{16}/ },
+    // Generic API keys / tokens assigned to key-like vars
+    {
+        name: "generic-api-key",
+        re: /(api[_-]?key|api[_-]?secret|access[_-]?token|auth[_-]?token)\s*[:=]\s*["'][A-Za-z0-9+/=_-]{20,}["']/i,
+    },
+    // Private key headers
+    {
+        name: "private-key",
+        re: /-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/,
+    },
+    // GitHub tokens
+    { name: "github-token", re: /gh[pousr]_[A-Za-z0-9_]{36,}/ },
+    // Generic password assignments
+    {
+        name: "password-assignment",
+        re: /(password|passwd|pwd)\s*[:=]\s*["'][^\s"']{8,}["']/i,
+    },
+    // Slack tokens
+    { name: "slack-token", re: /xox[baprs]-[0-9a-zA-Z-]+/ },
+    // Stripe keys
+    { name: "stripe-secret-key", re: /sk_live_[0-9a-zA-Z]{24,}/ },
+    { name: "stripe-restricted-key", re: /rk_live_[0-9a-zA-Z]{24,}/ },
+    // SendGrid
+    {
+        name: "sendgrid-key",
+        re: /SG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}/,
+    },
+];
+/** ARG_MAX guard: cap the number of file paths per `git diff` argv batch. */
+export const DEFAULT_CHUNK_SIZE = 512;
+/**
+ * maxBuffer for the content `git diff` read. Node's default is 1 MiB; a staged
+ * diff larger than that rejects and (caught) blocks every large legitimate
+ * commit with a cryptic buffer error. Raise the ceiling to a generous but
+ * BOUNDED 64 MiB so ordinary large commits scan, while a genuinely pathological
+ * diff still fails closed instead of exhausting memory.
+ */
+export const DIFF_MAX_BUFFER = 64 * 1024 * 1024;
+function defaultDeps() {
+    return {
+        execFile: async (cmd, args, opts) => {
+            const { stdout, stderr } = await execFileAsync(cmd, args, opts);
+            return { stdout: String(stdout), stderr: String(stderr) };
+        },
+        log: (m) => console.log(m),
+        chunkSize: DEFAULT_CHUNK_SIZE,
+    };
+}
+/** NUL-safe staged-file list (`-z` → split on "\0", drop the trailing empty). */
+async function stagedFiles(deps, projectDir) {
+    const { stdout } = await deps.execFile("git", ["diff", "--cached", "--name-only", "--diff-filter=ACM", "-z"], { cwd: projectDir });
+    return stdout.split("\0").filter((f) => f.length > 0);
+}
+function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+/**
+ * Walk a unified diff and report every ADDED line (`+`, never `+++`) that
+ * matches a secret pattern, tracking the new-file path and line number so a
+ * finding reads `path:line pattern`.
+ */
+export function scanDiff(diff) {
+    const findings = [];
+    let currentFile = "";
+    let newLine = 0;
+    for (const line of diff.split("\n")) {
+        if (line.startsWith("+++ ")) {
+            const p = line.slice(4).trim();
+            currentFile = p === "/dev/null" ? "" : p.replace(/^b\//, "");
+            continue;
+        }
+        if (line.startsWith("--- "))
+            continue;
+        const hunk = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+        if (hunk) {
+            newLine = Number.parseInt(hunk[1], 10);
+            continue;
+        }
+        if (line.startsWith("diff --git") ||
+            line.startsWith("index ") ||
+            line.startsWith("old mode") ||
+            line.startsWith("new mode") ||
+            line.startsWith("similarity ") ||
+            line.startsWith("rename ") ||
+            line.startsWith("new file") ||
+            line.startsWith("deleted file")) {
+            continue;
+        }
+        if (line.startsWith("+")) {
+            const content = line.slice(1);
+            for (const { name, re } of SECRET_PATTERNS) {
+                if (re.test(content)) {
+                    findings.push({ file: currentFile, line: newLine, pattern: name });
+                }
+            }
+            newLine++;
+        }
+        else if (line.startsWith("-")) {
+            // removed line — does not advance the new-file line counter
+        }
+        else {
+            // context (leading space) or blank line
+            newLine++;
+        }
+    }
+    return findings;
+}
+/**
+ * The `secrets` section factory. Injectable seams default to the real
+ * `git`-via-execFileAsync implementation; tests pass mocks. A thrown git error
+ * becomes a blocking `{ ok: false }` (never an unhandled rejection), matching
+ * the ciSection/tddSection hardening.
+ */
+export function secretsSection(overrides = {}) {
+    const deps = { ...defaultDeps(), ...overrides };
+    return {
+        id: "secrets",
+        blocking: true,
+        async run({ projectDir }) {
+            try {
+                const files = await stagedFiles(deps, projectDir);
+                if (files.length === 0)
+                    return { ok: true };
+                const findings = [];
+                for (const batch of chunk(files, deps.chunkSize)) {
+                    // `--no-color` is MANDATORY: under `color.ui=always` (or
+                    // `color.diff=always`) git emits ANSI escapes even to a pipe, so
+                    // added lines render as `\x1b[32m+secret\x1b[m` and both the
+                    // `+`/`+++ ` line checks in scanDiff fail — the scanner would then
+                    // find zero secrets and fail OPEN. Forcing color off keeps the diff
+                    // plain-text and the scan deterministic.
+                    const { stdout } = await deps.execFile("git", ["diff", "--no-color", "--cached", "--", ...batch], { cwd: projectDir, maxBuffer: DIFF_MAX_BUFFER });
+                    findings.push(...scanDiff(stdout));
+                }
+                if (findings.length === 0)
+                    return { ok: true };
+                const summary = findings
+                    .slice(0, 10)
+                    .map((f) => `${f.file || "<staged>"}:${f.line} ${f.pattern}`)
+                    .join("; ");
+                return {
+                    ok: false,
+                    detail: `${findings.length} potential secret(s): ${summary}`,
+                };
+            }
+            catch (e) {
+                return {
+                    ok: false,
+                    detail: e instanceof Error ? e.message : String(e),
+                };
+            }
+        },
+    };
+}
+//# sourceMappingURL=secrets.js.map

package/dist/commands/hooks.d.ts

@@ -10,10 +10,10 @@
  * behavior); a config that FAILS to validate exits 1 — a broken config never
  * silently skips a gate.
  *
- * S1a/S3 scope: the `ci` and `tdd` sections have bodies. The
- * secrets/permissions/deps sections have no factory yet (they land in S4); an
- * enabled-but-unregistered feature is skipped by `composeSections` until its
- * slice wires a factory.
+ * S1a/S3/S4 scope: the `ci`, `tdd`, `secrets`, `permissions` and `deps`
+ * sections all have factories now. `composeSections` still skips any enabled
+ * feature with no registered factory, so a future feature can land the same
+ * way.
  */
 import { type CIHooksConfig } from "../lib/ci-config.js";
 import type { Stack } from "../types/index.js";

package/dist/commands/hooks.js

@@ -10,14 +10,17 @@
  * behavior); a config that FAILS to validate exits 1 — a broken config never
  * silently skips a gate.
  *
- * S1a/S3 scope: the `ci` and `tdd` sections have bodies. The
- * secrets/permissions/deps sections have no factory yet (they land in S4); an
- * enabled-but-unregistered feature is skipped by `composeSections` until its
- * slice wires a factory.
+ * S1a/S3/S4 scope: the `ci`, `tdd`, `secrets`, `permissions` and `deps`
+ * sections all have factories now. `composeSections` still skips any enabled
+ * feature with no registered factory, so a future feature can land the same
+ * way.
  */
 import { spawn } from "node:child_process";
 import { findCIConfig, loadCIConfig, } from "../lib/ci-config.js";
 import { detectCIStack, runCI } from "./ci.js";
+import { depsSection } from "./hooks/sections/deps.js";
+import { permissionsSection } from "./hooks/sections/permissions.js";
+import { secretsSection } from "./hooks/sections/secrets.js";
 import { getTddTestCommand } from "./tdd.js";
 /** Fixed cheap→expensive order per hook (deterministic is a feature). */
 const PRE_COMMIT_ORDER = ["secrets", "permissions", "tdd", "ci"];
@@ -193,6 +196,12 @@ export function defaultRegistry(runCIImpl, log, tddDeps = {}) {
             runCommand: tddDeps.runCommand ?? runTestCommand,
             log: tddDeps.log ?? log,
         }),
+        // S4 security sections. Each resolves its git/fs/exec seams at run time
+        // via the section's own defaults; unit tests inject mocks by importing
+        // the factory directly (see src/commands/hooks/sections/*.test.ts).
+        secrets: () => secretsSection({ log }),
+        permissions: () => permissionsSection({ log }),
+        deps: () => depsSection({ log }),
     };
 }
 /** Resolve the parsed `hooks:` config for a project (null → default [ci]). */

package/dist/commands/init/steps/ghagga.d.ts

@@ -1,15 +1,14 @@
 import type { StepFn } from "../types.js";
 /**
- * Step 9: Install GHAGGA review system.
+ * Step 9: Install the local GHAGGA review module.
  *
  * - When ghagga is false, reports "skipped".
  * - Copies <MODULES_DIR>/ghagga → <project>/.javi-forge/modules/ghagga (no overwrite).
- * - For GitHub provider, also copies the ghagga-review.yml caller workflow into
- *   <project>/.github/workflows/.
  * - If module source dir is missing, reports "error" with "module not found".
  * - Errors are swallowed and reported as status:"error" — never thrown.
  *
- * Extracted VERBATIM from src/commands/init.ts (PR 3 of 6).
+ * The GitHub Action review workflow is intentionally NOT scaffolded — ghagga
+ * runs locally/self-hosted, not as a GitHub Action.
  */
 export declare const stepGhagga: StepFn;
 //# sourceMappingURL=ghagga.d.ts.map

package/dist/commands/init/steps/ghagga.js

@@ -1,23 +1,22 @@
 import path from "node:path";
 import fs from "fs-extra";
-import { FORGE_ROOT, MODULES_DIR } from "../../../constants.js";
+import { MODULES_DIR } from "../../../constants.js";
 import { ensureDirExists } from "../../../lib/common.js";
 import { report } from "../report.js";
 /**
- * Step 9: Install GHAGGA review system.
+ * Step 9: Install the local GHAGGA review module.
  *
  * - When ghagga is false, reports "skipped".
  * - Copies <MODULES_DIR>/ghagga → <project>/.javi-forge/modules/ghagga (no overwrite).
- * - For GitHub provider, also copies the ghagga-review.yml caller workflow into
- *   <project>/.github/workflows/.
  * - If module source dir is missing, reports "error" with "module not found".
  * - Errors are swallowed and reported as status:"error" — never thrown.
  *
- * Extracted VERBATIM from src/commands/init.ts (PR 3 of 6).
+ * The GitHub Action review workflow is intentionally NOT scaffolded — ghagga
+ * runs locally/self-hosted, not as a GitHub Action.
  */
 export const stepGhagga = async (ctx) => {
     const { projectDir, dryRun, onStep, options } = ctx;
-    const { ghagga, ciProvider } = options;
+    const { ghagga } = options;
     const stepId = "ghagga";
     report(onStep, stepId, "Install GHAGGA review system", "running");
     try {
@@ -31,15 +30,6 @@ export const stepGhagga = async (ctx) => {
                         overwrite: false,
                         errorOnExist: false,
                     });
-                    // Copy ghagga caller workflow to CI provider location
-                    if (ciProvider === "github") {
-                        const workflowSrc = path.join(FORGE_ROOT, "templates", "github", "ghagga-review.yml");
-                        if (await fs.pathExists(workflowSrc)) {
-                            const workflowDest = path.join(projectDir, ".github", "workflows", "ghagga-review.yml");
-                            await ensureDirExists(path.dirname(workflowDest));
-                            await fs.copy(workflowSrc, workflowDest, { overwrite: false });
-                        }
-                    }
                 }
                 report(onStep, stepId, "Install GHAGGA review system", "done");
             }

package/dist/commands/init/steps/security.d.ts

@@ -1,28 +1,18 @@
 import type { StepFn } from "../types.js";
 /**
- * Step 14: Scaffold security hooks.
+ * Step 14: Scaffold security hooks (hook-consolidation S4 fold).
  *
  * - When options.securityHooks is false, reports "skipped".
- * - When SECURITY_HOOKS_DIR templates are missing, reports "error".
- * - Otherwise copies the 6-layer git security hooks into
- *   ci-local/hooks/security/ (skipping existing files, chmod 0755) and copies
- *   the kiteguard-style runtime settings to .claude/settings.json when absent.
+ * - Otherwise:
+ *   1. Copies the kiteguard-style runtime settings to `.claude/settings.json`
+ *      when absent (KEPT — this is a real feature).
+ *   2. Merges the `hooks:` security sections for the selected reliability
+ *      profile into `.javi-forge/ci.yaml` via `setHookFeature` (creating a
+ *      minimal `version: 2` config when absent). The dispatcher composes these
+ *      sections at hook-run time (see src/commands/hooks.ts).
+ * - The old inert `ci-local/hooks/security/` git-hook copy is GONE (those hook
+ *   bodies were ported to TypeScript sections in S4).
  * - Errors are swallowed and reported as status:"error" — never thrown.
- *
- * Extracted VERBATIM from src/commands/init.ts (PR 5 of 6).
- * Grouped with stepHookProfile for cohesion — both manage ci-local/hooks/.
  */
 export declare const stepSecurityHooks: StepFn;
-/**
- * Step 14b: Write hook reliability profile.
- *
- * - When options.securityHooks is false, reports "skipped".
- * - Otherwise writes ci-local/hooks/profile.json with the resolved profile
- *   (defaults to "standard" when hookProfile is undefined).
- * - Errors are swallowed and reported as status:"error" — never thrown.
- *
- * Extracted VERBATIM from src/commands/init.ts (PR 5 of 6).
- * Grouped with stepSecurityHooks for cohesion — both manage ci-local/hooks/.
- */
-export declare const stepHookProfile: StepFn;
 //# sourceMappingURL=security.d.ts.map

package/dist/commands/init/steps/security.js

@@ -1,103 +1,83 @@
 import path from "node:path";
 import fs from "fs-extra";
 import { SECURITY_HOOKS_DIR } from "../../../constants.js";
+import { setHookFeature } from "../../../lib/ci-config.js";
 import { ensureDirExists } from "../../../lib/common.js";
 import { report } from "../report.js";
 /**
- * Step 14: Scaffold security hooks.
+ * Hook-feature preset per reliability profile (hook-consolidation S4).
  *
- * - When options.securityHooks is false, reports "skipped".
- * - When SECURITY_HOOKS_DIR templates are missing, reports "error".
- * - Otherwise copies the 6-layer git security hooks into
- *   ci-local/hooks/security/ (skipping existing files, chmod 0755) and copies
- *   the kiteguard-style runtime settings to .claude/settings.json when absent.
- * - Errors are swallowed and reported as status:"error" — never thrown.
- *
- * Extracted VERBATIM from src/commands/init.ts (PR 5 of 6).
- * Grouped with stepHookProfile for cohesion — both manage ci-local/hooks/.
+ * The old `stepHookProfile` wrote a `ci-local/hooks/profile.json` that had ZERO
+ * runtime readers (design D7). The selector is repurposed: the chosen profile
+ * now drives WHICH `hooks:` security sections get merged into
+ * `.javi-forge/ci.yaml`, using the EXISTING `HookProfile` values (no "relaxed"):
+ *   - strict   → secrets + permissions + deps (every section)
+ *   - standard → secrets + deps
+ *   - minimal  → CI gate only (no security sections)
  */
-export const stepSecurityHooks = async (ctx) => {
-    const { projectDir, dryRun, onStep, options } = ctx;
-    const { securityHooks } = options;
-    const stepId = "security-hooks";
-    report(onStep, stepId, "Scaffold security hooks", "running");
-    try {
-        if (securityHooks) {
-            if (await fs.pathExists(SECURITY_HOOKS_DIR)) {
-                if (!dryRun) {
-                    // Copy 6-layer git security hooks into ci-local/hooks/security/
-                    const secHooksDest = path.join(projectDir, "ci-local", "hooks", "security");
-                    await ensureDirExists(secHooksDest);
-                    const hookFiles = await fs.readdir(SECURITY_HOOKS_DIR);
-                    const gitHooks = hookFiles.filter((f) => !f.endsWith(".json"));
-                    for (const hook of gitHooks) {
-                        const src = path.join(SECURITY_HOOKS_DIR, hook);
-                        const dest = path.join(secHooksDest, hook);
-                        await fs.copy(src, dest, { overwrite: false });
-                        await fs.chmod(dest, 0o755);
-                    }
-                    // Copy runtime security settings (kiteguard-style) to .claude/
-                    const settingsSrc = path.join(SECURITY_HOOKS_DIR, "claude-settings-security.json");
-                    if (await fs.pathExists(settingsSrc)) {
-                        const claudeDir = path.join(projectDir, ".claude");
-                        await ensureDirExists(claudeDir);
-                        const settingsDest = path.join(claudeDir, "settings.json");
-                        if (!(await fs.pathExists(settingsDest))) {
-                            await fs.copy(settingsSrc, settingsDest);
-                        }
-                    }
-                }
-                report(onStep, stepId, "Scaffold security hooks", "done", dryRun
-                    ? "dry-run: would scaffold security hooks"
-                    : "6 git layers + runtime hooks");
-            }
-            else {
-                report(onStep, stepId, "Scaffold security hooks", "error", "security-hooks templates not found");
-            }
-        }
-        else {
-            report(onStep, stepId, "Scaffold security hooks", "skipped", "not selected");
-        }
-    }
-    catch (e) {
-        report(onStep, stepId, "Scaffold security hooks", "error", String(e));
-    }
+const PROFILE_PRESET = {
+    minimal: { preCommit: [], prePush: [] },
+    standard: { preCommit: ["secrets"], prePush: ["deps"] },
+    strict: { preCommit: ["secrets", "permissions"], prePush: ["deps"] },
 };
 /**
- * Step 14b: Write hook reliability profile.
+ * Step 14: Scaffold security hooks (hook-consolidation S4 fold).
  *
  * - When options.securityHooks is false, reports "skipped".
- * - Otherwise writes ci-local/hooks/profile.json with the resolved profile
- *   (defaults to "standard" when hookProfile is undefined).
+ * - Otherwise:
+ *   1. Copies the kiteguard-style runtime settings to `.claude/settings.json`
+ *      when absent (KEPT — this is a real feature).
+ *   2. Merges the `hooks:` security sections for the selected reliability
+ *      profile into `.javi-forge/ci.yaml` via `setHookFeature` (creating a
+ *      minimal `version: 2` config when absent). The dispatcher composes these
+ *      sections at hook-run time (see src/commands/hooks.ts).
+ * - The old inert `ci-local/hooks/security/` git-hook copy is GONE (those hook
+ *   bodies were ported to TypeScript sections in S4).
  * - Errors are swallowed and reported as status:"error" — never thrown.
- *
- * Extracted VERBATIM from src/commands/init.ts (PR 5 of 6).
- * Grouped with stepSecurityHooks for cohesion — both manage ci-local/hooks/.
  */
-export const stepHookProfile = async (ctx) => {
+export const stepSecurityHooks = async (ctx) => {
     const { projectDir, dryRun, onStep, options } = ctx;
     const { securityHooks, hookProfile } = options;
-    const stepId = "hook-profile";
-    report(onStep, stepId, "Write hook reliability profile", "running");
+    const stepId = "security-hooks";
+    report(onStep, stepId, "Scaffold security hooks", "running");
     try {
-        if (securityHooks) {
-            if (!dryRun) {
-                const hooksDir = path.join(projectDir, "ci-local", "hooks");
-                await ensureDirExists(hooksDir);
-                const profilePath = path.join(hooksDir, "profile.json");
-                const resolvedProfile = hookProfile ?? "standard";
-                await fs.writeJson(profilePath, { profile: resolvedProfile }, { spaces: 2 });
+        if (!securityHooks) {
+            report(onStep, stepId, "Scaffold security hooks", "skipped", "not selected");
+            return;
+        }
+        const profile = hookProfile ?? "standard";
+        const preset = PROFILE_PRESET[profile];
+        if (dryRun) {
+            report(onStep, stepId, "Scaffold security hooks", "done", `dry-run: would merge ${profile} hooks preset + copy .claude/settings.json`);
+            return;
+        }
+        // 1. Copy the kiteguard-style runtime security settings to .claude/.
+        const settingsSrc = path.join(SECURITY_HOOKS_DIR, "claude-settings-security.json");
+        if (await fs.pathExists(settingsSrc)) {
+            const claudeDir = path.join(projectDir, ".claude");
+            await ensureDirExists(claudeDir);
+            const settingsDest = path.join(claudeDir, "settings.json");
+            if (!(await fs.pathExists(settingsDest))) {
+                await fs.copy(settingsSrc, settingsDest);
             }
-            report(onStep, stepId, "Write hook reliability profile", "done", dryRun
-                ? `dry-run: would write profile.json (${hookProfile ?? "standard"})`
-                : `ci-local/hooks/profile.json (${hookProfile ?? "standard"})`);
         }
-        else {
-            report(onStep, stepId, "Write hook reliability profile", "skipped", "security hooks not selected");
+        // 2. Merge the profile's security sections into .javi-forge/ci.yaml.
+        for (const feature of preset.preCommit) {
+            await setHookFeature(projectDir, "pre-commit", feature, true);
+        }
+        for (const feature of preset.prePush) {
+            await setHookFeature(projectDir, "pre-push", feature, true);
         }
+        const merged = [
+            ...preset.preCommit.map((f) => `pre-commit.${f}`),
+            ...preset.prePush.map((f) => `pre-push.${f}`),
+        ];
+        report(onStep, stepId, "Scaffold security hooks", "done", merged.length > 0
+            ? `${profile} preset: ${merged.join(", ")}`
+            : `${profile} preset: CI gate only (no security sections)`);
     }
     catch (e) {
-        report(onStep, stepId, "Write hook reliability profile", "error", String(e));
+        report(onStep, stepId, "Scaffold security hooks", "error", String(e));
     }
 };
 //# sourceMappingURL=security.js.map

package/dist/commands/init.js

@@ -14,7 +14,7 @@ import { stepManifest } from "./init/steps/manifest.js";
 import { stepMemory } from "./init/steps/memory.js";
 import { stepMock } from "./init/steps/mock.js";
 import { stepSDD } from "./init/steps/sdd.js";
-import { stepHookProfile, stepSecurityHooks } from "./init/steps/security.js";
+import { stepSecurityHooks } from "./init/steps/security.js";
 /**
  * Main init orchestrator: bootstraps a project with CI, git hooks,
  * memory module, AI config sync, SDD, ghagga, and friends.
@@ -43,7 +43,6 @@ export async function initProject(options, onStep) {
     await stepClaudeMd(ctx);
     await stepDockerDeploy(ctx);
     await stepSecurityHooks(ctx);
-    await stepHookProfile(ctx);
     await stepCodeGraph(ctx);
     await stepLocalAi(ctx);
     await stepAgentSkills(ctx);

package/dist/commands/skills/analysis.js

@@ -1,4 +1,5 @@
-import { CONTRADICTION_PAIRS, DEFAULT_BUDGET } from "./constants.js";
+import fs from "fs-extra";
+import { CHARS_PER_TOKEN, CONTRADICTION_PAIRS, DEFAULT_BUDGET, } from "./constants.js";
 import { detectDirectiveClash } from "./directives.js";
 import { discoverSkills, estimateTokens, parseSkillFile } from "./parsing.js";
 // ── Budget Optimization ─────────────────────────────────────────────────────
@@ -98,6 +99,12 @@ export async function findConflicts(skillsDir) {
         const parsed = await parseSkillFile(sp);
         if (!parsed)
             continue;
+        // A skipped file has no readable rules to compare. Don't treat its empty
+        // rule list as "no conflicts" — it is surfaced as a skip in the budget
+        // section (calculateBudget always runs alongside conflict detection), so
+        // skip it here explicitly rather than letting it pass silently.
+        if (parsed.skip)
+            continue;
         for (const rule of parsed.rules) {
             allRules.push({
                 skillName: parsed.name,
@@ -138,10 +145,32 @@ export async function calculateBudget(skillsDir, budget = DEFAULT_BUDGET) {
         const parsed = await parseSkillFile(sp);
         if (!parsed)
             continue;
+        // Token count reflects the bytes actually kept by the guarded read, so a
+        // skipped or truncated skill is reported rather than counted as normal.
+        const note = parsed.skip
+            ? `skipped: ${parsed.skip.message}`
+            : parsed.truncated
+                ? "truncated: read budget reached"
+                : undefined;
+        // A skipped skill has empty `rawContent`, so token estimation from it would
+        // be 0 and the file would sort last — the budget tool would hide the very
+        // oversized file it exists to flag. Fall back to the real on-disk byte size
+        // so an unread skill still counts toward the total and over-budget check.
+        let tokens = estimateTokens(parsed.rawContent);
+        if (parsed.skip) {
+            try {
+                const { size } = await fs.stat(sp);
+                tokens = Math.ceil(size / CHARS_PER_TOKEN);
+            }
+            catch {
+                // Vanished between discovery and stat — leave 0; the note still flags it.
+            }
+        }
         entries.push({
             skillName: parsed.name,
             skillPath: sp,
-            tokens: estimateTokens(parsed.rawContent),
+            tokens,
+            ...(note ? { note } : {}),
         });
     }
     // Sort by token count descending (biggest consumers first)

package/dist/commands/skills/benchmark.js

@@ -9,6 +9,16 @@ export async function benchmarkSkill(skillPath) {
     const parsed = await parseSkillFile(skillPath);
     if (!parsed)
         return null;
+    // A file that could not be read has no structure to benchmark. Reporting it
+    // as a skill that failed every check is misleading — mark it unread instead.
+    if (parsed.skip) {
+        return {
+            skillName: parsed.name,
+            checks: [],
+            passRate: 0,
+            unread: parsed.skip.message,
+        };
+    }
     const checks = [];
     // Check 1: Has YAML frontmatter with name
     checks.push({

package/dist/commands/skills/constants.d.ts

@@ -6,5 +6,10 @@ export declare const CHARS_PER_TOKEN = 4;
 export declare const DEFAULT_THRESHOLD = 50;
 /** Default registry quality threshold */
 export declare const DEFAULT_REGISTRY_THRESHOLD = 60;
+/**
+ * Hard ceiling for a SKILL.md. A skill file past this is not a skill — it is a
+ * dumped log or a vendored bundle — so it is skipped instead of truncated.
+ */
+export declare const MAX_SKILL_BYTES: number;
 export declare const CONTRADICTION_PAIRS: [RegExp, RegExp][];
 //# sourceMappingURL=constants.d.ts.map

package/dist/commands/skills/constants.js

@@ -8,6 +8,11 @@ export const CHARS_PER_TOKEN = 4;
 export const DEFAULT_THRESHOLD = 50;
 /** Default registry quality threshold */
 export const DEFAULT_REGISTRY_THRESHOLD = 60;
+/**
+ * Hard ceiling for a SKILL.md. A skill file past this is not a skill — it is a
+ * dumped log or a vendored bundle — so it is skipped instead of truncated.
+ */
+export const MAX_SKILL_BYTES = 1024 * 1024;
 // ── Contradiction keywords (pairs that signal opposite intent) ───────────────
 export const CONTRADICTION_PAIRS = [
     [/\buse semicolons\b/i, /\bno semicolons\b/i],

package/dist/commands/skills/parsing.d.ts

@@ -1,12 +1,27 @@
+import { type SafeReadFailureReason } from "../../lib/safe-read.js";
 /** Estimate token count from a string */
 export declare function estimateTokens(text: string): number;
-/** Read a SKILL.md and extract its name + critical rules section */
-export declare function parseSkillFile(skillPath: string): Promise<{
+/** Why a SKILL.md could not be analysed — reportable, never thrown */
+export interface SkillReadSkip {
+    reason: SafeReadFailureReason;
+    message: string;
+}
+export interface ParsedSkillFile {
     name: string;
     rules: string[];
     rawContent: string;
     triggers: string[];
-} | null>;
+    /**
+     * Non-null when the file could not be read as analysable text (binary,
+     * oversized, permission denied). `rawContent` is empty in that case, so
+     * callers can report the skip instead of scoring an empty skill.
+     */
+    skip: SkillReadSkip | null;
+    /** True when the file was longer than the read budget and got cut short. */
+    truncated: boolean;
+}
+/** Read a SKILL.md and extract its name + critical rules section */
+export declare function parseSkillFile(skillPath: string): Promise<ParsedSkillFile | null>;
 /** Extract critical rules from markdown content */
 export declare function extractCriticalRules(content: string): string[];
 /** Extract trigger keywords from a skill description */