javi-forge 1.26.0 → 1.27.0

package/ci-local/hooks/commit-msg

@@ -1,6 +1,13 @@
 #!/bin/bash
 set -e
 # =============================================================================
+# LEGACY — retained for reference only (hook-consolidation).
+# The canonical hook mechanism is now `.git/hooks/` written by `installCIHooks`
+# (javi-forge ci init / init). The shipped commit-msg shim lives in
+# assets/hooks/commit-msg; `javi-forge init` no longer copies this directory or
+# sets `core.hooksPath=ci-local/hooks`. This body is kept for historical
+# reference and is NOT the source of truth. See docs/commands.md → hooks.
+# =============================================================================
 # COMMIT-MSG: Block accidental AI-attribution in commit messages
 # =============================================================================
 # Best-effort, NOT an adversarial-grade security control.

package/ci-local/hooks/pre-commit

@@ -1,5 +1,13 @@
 #!/bin/bash
 # =============================================================================
+# LEGACY — retained for reference only (hook-consolidation).
+# The canonical hook mechanism is now `.git/hooks/` written by `installCIHooks`
+# (javi-forge ci init / init), whose static shims exec the dispatcher
+# `javi-forge hooks run <name>`. `javi-forge init` no longer copies this
+# directory or sets `core.hooksPath=ci-local/hooks`; a repo still on that legacy
+# path is auto-migrated on the next install. This body is kept for historical
+# reference and is NOT the source of truth. See docs/commands.md → hooks.
+# =============================================================================
 # PRE-COMMIT: Quick CI check via javi-forge
 # =============================================================================
 # Requires: npm install -g javi-forge

package/ci-local/hooks/pre-push

@@ -1,5 +1,13 @@
 #!/bin/bash
 # =============================================================================
+# LEGACY — retained for reference only (hook-consolidation).
+# The canonical hook mechanism is now `.git/hooks/` written by `installCIHooks`
+# (javi-forge ci init / init), whose static shims exec the dispatcher
+# `javi-forge hooks run <name>`. `javi-forge init` no longer copies this
+# directory or sets `core.hooksPath=ci-local/hooks`; a repo still on that legacy
+# path is auto-migrated on the next install. This body is kept for historical
+# reference and is NOT the source of truth. See docs/commands.md → hooks.
+# =============================================================================
 # PRE-PUSH: Full CI simulation via javi-forge
 # =============================================================================
 # Requires: npm install -g javi-forge

package/dist/cli/dispatch/ci.js

@@ -83,7 +83,7 @@ export async function handleCi(cli, ctx) {
         }
         if (installed.length > 0) {
             console.log(`✓ Installed git hooks: ${installed.join(", ")}`);
-            console.log("  Hooks call javi-forge ci (with npx fallback)");
+            console.log("  Hooks call javi-forge hooks run (with npx fallback)");
         }
         // Upgrades are reported DISTINCTLY from fresh installs: replacing an
         // older javi-forge hook is not the same event as writing a new one.

package/dist/cli/dispatch/skills-cmd.js

@@ -57,6 +57,10 @@ export async function handleSkillsCmd(cli, ctx) {
                 console.error(`\u2717 Skill not found: ${skillPath}`);
                 process.exit(1);
             }
+            if (result.unread) {
+                console.error(`\u2717 Skill could not be scored \u2014 ${result.unread}: ${skillPath}`);
+                process.exit(1);
+            }
             console.log(`\nSkill: ${result.skillName}`);
             console.log(`  Completeness:      ${result.completeness}/100`);
             console.log(`  Clarity:           ${result.clarity}/100`);
@@ -77,6 +81,10 @@ export async function handleSkillsCmd(cli, ctx) {
             console.error(`\u2717 Skill not found: ${skillPath}`);
             process.exit(1);
         }
+        if (result.unread) {
+            console.error(`\u2717 Skill could not be benchmarked \u2014 ${result.unread}: ${skillPath}`);
+            process.exit(1);
+        }
         console.log(`\nBenchmark: ${result.skillName}`);
         for (const check of result.checks) {
             const icon = check.passed ? "\u2713" : "\u2717";

package/dist/commands/ci.js

@@ -487,7 +487,11 @@ export async function runCI(options, onStep, onGateOutcome) {
     try {
         const ctxResult = await refreshContextDir(projectDir);
         if (ctxResult) {
-            report(onStep, stepContext, "Refresh .context/ directory", "done", "INDEX.md + summary.md updated");
+            // An unreadable manifest is reported, not silently treated as no deps.
+            const detail = ctxResult.warnings.length > 0
+                ? `INDEX.md + summary.md updated (manifest warnings: ${ctxResult.warnings.join("; ")})`
+                : "INDEX.md + summary.md updated";
+            report(onStep, stepContext, "Refresh .context/ directory", "done", detail);
         }
         else {
             report(onStep, stepContext, "Refresh .context/ directory", "skipped", "no .context/ or no manifest");

package/dist/commands/doctor.js

@@ -319,6 +319,15 @@ export async function runDoctor(projectDir) {
                 status: "ok",
                 detail: "INDEX.md + summary.md updated",
             });
+            // A manifest that could not be read is not "no dependencies" — surface
+            // each warning so an unreadable/oversized/invalid manifest is visible.
+            for (const warning of result.warnings) {
+                contextChecks.push({
+                    label: "dependency manifest",
+                    status: "fail",
+                    detail: warning,
+                });
+            }
         }
         else {
             contextChecks.push({

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/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 */

package/dist/commands/skills/parsing.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import fs from "fs-extra";
 import { parseFrontmatter } from "../../lib/frontmatter.js";
-import { CHARS_PER_TOKEN } from "./constants.js";
+import { describeSafeReadFailure, safeReadFile, } from "../../lib/safe-read.js";
+import { CHARS_PER_TOKEN, MAX_SKILL_BYTES } from "./constants.js";
 // ── Helpers ──────────────────────────────────────────────────────────────────
 /** Estimate token count from a string */
 export function estimateTokens(text) {
@@ -11,7 +12,24 @@ export function estimateTokens(text) {
 export async function parseSkillFile(skillPath) {
     if (!(await fs.pathExists(skillPath)))
         return null;
-    const raw = await fs.readFile(skillPath, "utf-8");
+    const read = await safeReadFile(skillPath, {
+        hardRejectOverBytes: MAX_SKILL_BYTES,
+    });
+    if (!read.ok) {
+        // A path that vanished between the existence check and the read is the
+        // same "no such skill" case the caller already handles with null.
+        if (read.reason === "not-found" || read.reason === "not-a-file")
+            return null;
+        return {
+            name: path.basename(path.dirname(skillPath)),
+            rules: [],
+            rawContent: "",
+            triggers: [],
+            skip: { reason: read.reason, message: describeSafeReadFailure(read) },
+            truncated: false,
+        };
+    }
+    const raw = read.content;
     const fm = parseFrontmatter(raw);
     const rawName = fm?.data?.name;
     const name = typeof rawName === "string"
@@ -23,7 +41,15 @@ export async function parseSkillFile(skillPath) {
     const rawDesc = fm?.data?.description;
     const description = typeof rawDesc === "string" ? rawDesc : "";
     const triggers = extractTriggers(description);
-    return { name, rules, rawContent: raw, triggers };
+    // rawContent is the kept text, so token estimates reflect what was analysed.
+    return {
+        name,
+        rules,
+        rawContent: raw,
+        triggers,
+        skip: null,
+        truncated: read.truncated,
+    };
 }
 /** Extract critical rules from markdown content */
 export function extractCriticalRules(content) {

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

@@ -1,10 +1,11 @@
 import type { SkillGrade, SkillRegistryGateResult, SkillScore } from "../../types/index.js";
-type ParsedSkill = {
-    name: string;
-    rules: string[];
-    rawContent: string;
-    triggers: string[];
-};
+import { type ParsedSkillFile } from "./parsing.js";
+/**
+ * The fields the dimension scorers read. Derived from `ParsedSkillFile` with
+ * `Pick` (not a hand-copied shape) so the `skip` field can never be silently
+ * dropped: a skipped parse is caught in `scoreSkill` before it reaches a scorer.
+ */
+type ParsedSkill = Pick<ParsedSkillFile, "name" | "rules" | "rawContent" | "triggers">;
 /**
  * Score completeness (0-100): frontmatter fields, critical rules, structure.
  */

package/dist/commands/skills/scoring.js

@@ -1,5 +1,5 @@
 import { DEFAULT_REGISTRY_THRESHOLD, DEFAULT_THRESHOLD } from "./constants.js";
-import { estimateTokens, parseSkillFile } from "./parsing.js";
+import { estimateTokens, parseSkillFile, } from "./parsing.js";
 import { ACTION_VERBS, VAGUE_TERMS } from "./rules.js";
 // ── Dangerous content patterns (private to scoreSafety) ─────────────────────
 /** Dangerous patterns in skill content that indicate safety risks */
@@ -243,6 +243,26 @@ export async function scoreSkill(skillPath, threshold = DEFAULT_THRESHOLD) {
     const parsed = await parseSkillFile(skillPath);
     if (!parsed)
         return null;
+    // A file that could not be read is NOT a zero-content skill. Scoring it would
+    // invent a grade over an empty string — worse, `scoreSafety` starts at 100
+    // and finds no dangerous patterns in nothing, so an unreadable file would
+    // report perfect safety. Represent it as unread and fail closed instead.
+    if (parsed.skip) {
+        return {
+            skillName: parsed.name,
+            completeness: 0,
+            clarity: 0,
+            testability: 0,
+            tokenEfficiency: 0,
+            safety: 0,
+            agentReadiness: 0,
+            overall: 0,
+            grade: "F",
+            threshold,
+            passing: false,
+            unread: parsed.skip.message,
+        };
+    }
     const completeness = scoreCompleteness(parsed);
     const clarity = scoreClarity(parsed);
     const testability = scoreTestability(parsed);
@@ -279,6 +299,16 @@ export async function registryGate(skillPath, threshold = DEFAULT_REGISTRY_THRES
     const score = await scoreSkill(skillPath, threshold);
     if (!score)
         return null;
+    // An unread skill can never be accepted into the registry: it was not scored,
+    // so it cannot clear any threshold. Reject it with an explicit reason.
+    if (score.unread) {
+        return {
+            skillName: score.skillName,
+            score,
+            accepted: false,
+            reason: `Rejected: could not read skill (${score.unread}) — not scored`,
+        };
+    }
     const accepted = score.passing;
     let reason;
     if (!accepted) {

package/dist/lib/context.d.ts

@@ -1,9 +1,28 @@
 import type { InitOptions, StackContextEntry } from "../types/index.js";
 export declare function buildIndexMd(projectName: string, stackCtx: StackContextEntry, ciProvider: string, memory: string): string;
 export declare function buildSummaryMd(projectName: string, stack: string, ciProvider: string, memory: string, modules: string[], dependencies?: string[]): string;
+/**
+ * Dependency detection outcome. `warnings` explains every manifest that could
+ * not be read or parsed, so a failure is distinguishable from "no dependencies"
+ * instead of being swallowed by a blanket catch.
+ */
+export interface DependencyDetection {
+    dependencies: string[];
+    warnings: string[];
+}
+/**
+ * Detect top-level dependencies from project manifest files, reporting why a
+ * manifest was skipped. Returns up to 10 dependency names (key deps only).
+ */
+export declare function detectDependenciesDetailed(projectDir: string, stack: string): Promise<DependencyDetection>;
 /**
  * Detect top-level dependencies from project manifest files.
  * Returns up to 10 dependency names (key deps only, not devDeps).
+ *
+ * List-returning convenience over `detectDependenciesDetailed`. It DISCARDS the
+ * read/parse warnings — an unreadable manifest is indistinguishable from an
+ * honest empty list through this function. Callers that must tell those two
+ * apart (like `refreshContextDir`) call `detectDependenciesDetailed` directly.
  */
 export declare function detectDependencies(projectDir: string, stack: string): Promise<string[]>;
 /**
@@ -23,5 +42,8 @@ export declare function refreshContextDir(projectDir: string): Promise<{
     index: string;
     summary: string;
     updated: boolean;
+    /** Manifest read/parse warnings — surfaced so an unreadable manifest is not
+     * silently reported as a project with no dependencies. */
+    warnings: string[];
 } | null>;
 //# sourceMappingURL=context.d.ts.map