javi-forge 1.28.0 → 1.29.0

package/dist/lib/plugin.js

@@ -4,8 +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";
+import { evaluateCoverageGate, scanFailureMessage, } from "./skill-install-gate.js";
+import { scanSkillsWithCoverage } from "./skill-scanner.js";
 const KEBAB_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const SEMVER_RE = /^\d+\.\d+\.\d+$/;
 // ── Validation ──────────────────────────────────────────────────────────────
@@ -158,54 +158,27 @@ export async function installPlugin(source, options = {}) {
             // 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 = [];
+            // verdict, so no force branch consults it). The refusal policy +
+            // message-building is shared with plugin import via
+            // evaluateCoverageGate (R2-001).
+            let coverage;
             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 });
+                coverage = await scanSkillsWithCoverage(tmpDir, declaredPaths);
             }
             catch (scanError) {
-                const msg = scanError instanceof Error ? scanError.message : String(scanError);
                 return {
                     success: false,
-                    error: `skillguard scan failed — ${msg}`,
+                    refused: true,
+                    error: scanFailureMessage(scanError),
                 };
             }
-            if (!gate.allowed) {
-                const blocked = gate.rejected.filter((r) => r.verdict === "block").length;
-                const unscannable = gate.rejected.filter((r) => r.verdict === "unscannable").length;
+            const decision = evaluateCoverageGate(coverage, { force });
+            if (decision.refusalError) {
                 return {
                     success: false,
-                    error: `skillguard: install refused — ${gate.rejected.length} rejected (${blocked} blocked, ${unscannable} unscannable)\n${formatBatchReport(declaredResults)}`,
+                    refused: true,
+                    error: decision.refusalError,
                 };
             }
             // Remove existing version if present

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

@@ -1,18 +1,22 @@
 /**
  * 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.
+ * Pure helpers: verdict evaluation ({@link evaluateInstallGate}) and the
+ * coverage refusal policy + message-building ({@link evaluateCoverageGate},
+ * {@link scanFailureMessage}) live in exactly one place so all three
+ * entrypoints (plugin add, plugin import, skills auto-install) share
+ * identical force semantics and byte-identical refusal messages (R2-001).
+ * 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.
+ * any symlink, case-colliding declared dirs, empty/missing `skills` on import,
+ * declared paths escaping the source dir) are NOT verdicts —
+ * `evaluateCoverageGate` enforces the walk-derived ones BEFORE the verdict
+ * gate runs, so `force` can never lift them either.
  */
-import type { SkillScanResult } from "./skill-scanner.js";
+import type { SkillCoverageScan, SkillScanResult } from "./skill-scanner.js";
 export interface InstallGateDecision {
     allowed: boolean;
     /** Rejected results when `!allowed`, else `[]`. */
@@ -28,4 +32,36 @@ export interface InstallGateDecision {
 export declare function evaluateInstallGate(results: SkillScanResult[], options?: {
     force?: boolean;
 }): InstallGateDecision;
+export interface CoverageGateDecision {
+    /** Verdict-gate evaluation of the declared results. */
+    gate: InstallGateDecision;
+    /**
+     * Refusal message when the install must be refused, else `null`
+     * (⇔ the install proceeds). Manifest-integrity refusals come first
+     * (errors → symlinks → undeclared — block-level, force never lifts),
+     * then the verdict refusal (`!gate.allowed`). Messages are the
+     * byte-identical UX contract both package entrypoints share (spec:
+     * "refusal output reuses scanner reports"; R2-001: the refusal policy +
+     * message-building lives in exactly one place).
+     */
+    refusalError: string | null;
+}
+/**
+ * Shared refusal policy for the coverage walk + verdict gate (R2-001) — the
+ * chain both `plugin add` and `plugin import` run between
+ * `scanSkillsWithCoverage` and placement. A `null` refusalError means the
+ * install may proceed; any non-null message is a block-level refusal the
+ * caller returns verbatim (`force` never lifts integrity refusals; the
+ * verdict branch already encodes the force rule via {@link evaluateInstallGate}).
+ */
+export declare function evaluateCoverageGate(coverage: SkillCoverageScan, options?: {
+    force?: boolean;
+}): CoverageGateDecision;
+/**
+ * Byte-identical message for the scanner-error deny (D7): a throw from the
+ * coverage walk or verdict evaluation is not a verdict, so no force branch
+ * consults it — the install is denied unconditionally (R2-001: shared by
+ * both package entrypoints).
+ */
+export declare function scanFailureMessage(error: unknown): string;
 //# sourceMappingURL=skill-install-gate.d.ts.map

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

@@ -1,18 +1,22 @@
 /**
  * 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.
+ * Pure helpers: verdict evaluation ({@link evaluateInstallGate}) and the
+ * coverage refusal policy + message-building ({@link evaluateCoverageGate},
+ * {@link scanFailureMessage}) live in exactly one place so all three
+ * entrypoints (plugin add, plugin import, skills auto-install) share
+ * identical force semantics and byte-identical refusal messages (R2-001).
+ * 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.
+ * any symlink, case-colliding declared dirs, empty/missing `skills` on import,
+ * declared paths escaping the source dir) are NOT verdicts —
+ * `evaluateCoverageGate` enforces the walk-derived ones BEFORE the verdict
+ * gate runs, so `force` can never lift them either.
  */
-import { isRejectedVerdict } from "./skill-scanner.js";
+import { formatBatchReport, isRejectedVerdict } from "./skill-scanner.js";
 /**
  * Evaluate a set of declared-skill scan results against the install gate.
  *
@@ -27,4 +31,69 @@ export function evaluateInstallGate(results, options) {
     const allowed = !hasBlock && (rejected.length === 0 || force);
     return { allowed, rejected: allowed ? [] : rejected };
 }
+/**
+ * Shared refusal policy for the coverage walk + verdict gate (R2-001) — the
+ * chain both `plugin add` and `plugin import` run between
+ * `scanSkillsWithCoverage` and placement. A `null` refusalError means the
+ * install may proceed; any non-null message is a block-level refusal the
+ * caller returns verbatim (`force` never lifts integrity refusals; the
+ * verdict branch already encodes the force rule via {@link evaluateInstallGate}).
+ */
+export function evaluateCoverageGate(coverage, options) {
+    // 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 {
+            gate: { allowed: false, rejected: [] },
+            refusalError: `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")}`,
+        };
+    }
+    // FU-5 (F3 residual): a declared dir with case-colliding on-disk twins
+    // is ambiguous — the declared scan read one twin while both install.
+    const ambiguous = coverage.ambiguousDeclaredDirs ?? [];
+    if (ambiguous.length > 0) {
+        return {
+            gate: { allowed: false, rejected: [] },
+            refusalError: `skillguard: install refused — ambiguous declared skill dir(s) (case-colliding on-disk dirs; manifest-integrity, force never lifts):\n${ambiguous.map((p) => `  ${p}`).join("\n")}`,
+        };
+    }
+    if (coverage.symlinks.length > 0) {
+        return {
+            gate: { allowed: false, rejected: [] },
+            refusalError: `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 {
+            gate: { allowed: false, rejected: [] },
+            refusalError: `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")}`,
+        };
+    }
+    const gate = evaluateInstallGate(coverage.declared, options);
+    if (!gate.allowed) {
+        const blocked = gate.rejected.filter((r) => r.verdict === "block").length;
+        const unscannable = gate.rejected.filter((r) => r.verdict === "unscannable").length;
+        return {
+            gate,
+            // Lead line names the rejected count; the batch report renders
+            // the FULL declared set so the header/rows reflect every scanned
+            // skill (D6, JD-014).
+            refusalError: `skillguard: install refused — ${gate.rejected.length} rejected (${blocked} blocked, ${unscannable} unscannable)\n${formatBatchReport(coverage.declared)}`,
+        };
+    }
+    return { gate, refusalError: null };
+}
+/**
+ * Byte-identical message for the scanner-error deny (D7): a throw from the
+ * coverage walk or verdict evaluation is not a verdict, so no force branch
+ * consults it — the install is denied unconditionally (R2-001: shared by
+ * both package entrypoints).
+ */
+export function scanFailureMessage(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return `skillguard scan failed — ${msg}`;
+}
 //# sourceMappingURL=skill-install-gate.js.map

package/dist/lib/skill-scanner.d.ts

@@ -107,6 +107,20 @@ export interface SkillCoverageScan {
      * proceed un-scanned.
      */
     errors: string[];
+    /**
+     * Distinct real on-disk dirs that case-collide with a DECLARED dir (FU-5,
+     * F3 residual): two or more on-disk dirs whose lowercased paths are equal
+     * AND match a declared dir — e.g. declared `skills/alpha` with on-disk
+     * siblings `skills/alpha` + `skills/Alpha` on a case-sensitive FS.
+     * Lowercased declared-dir membership (R1-F2-N1) cannot tell the twins
+     * apart: both pass membership (neither SKILL.md lands in `undeclared`)
+     * while the declared scan reads only one of them — the other installs
+     * un-scanned. The caller refuses on this (manifest-integrity, block-
+     * level, force never lifts). Absent or empty when no declared dir
+     * case-collides; a single case-folded on-disk dir (no twin) is NOT
+     * ambiguous — it resolves via the normal case-fold lookup.
+     */
+    ambiguousDeclaredDirs?: string[];
 }
 /**
  * SKILL.md-only coverage walk for the install gates (JD-006/JD-007).
@@ -121,6 +135,29 @@ export interface SkillCoverageScan {
  * {@link scanSkillFile} afterwards (JD-005).
  */
 export declare function scanSkillsWithCoverage(dir: string, declaredPaths: string[]): Promise<SkillCoverageScan>;
+export interface PathContainmentCheck {
+    /** True when the entry stays inside the root lexically AND by realpath. */
+    ok: boolean;
+    /** Absolute lexical resolution of `entry` under `rootAbs`. */
+    entryAbs: string;
+    /** Which containment check failed when `!ok`. */
+    violation?: "lexical" | "realpath";
+}
+/**
+ * Containment core (R2-002) — the ONE implementation of the lexical +
+ * realpath containment policy (JD-003): an entry must stay inside the root
+ * both lexically (`../../x`, absolute paths) and by realpath, so an in-tree
+ * symlink cannot redirect a read outside the staged clone. Realpath
+ * resolution is best-effort: a missing declared dir has no realpath yet, in
+ * which case lexical containment is the whole guard (the coverage walk later
+ * reports it as a missing/unscannable declared skill).
+ *
+ * Two surfaces wrap this core with their own error shapes (both bound by
+ * tests — keep the messages distinct): {@link resolveContained} (throwing;
+ * used by the coverage walk) and `skillPathContained` in agent-skills.ts
+ * (non-throwing `{ ok, reason }`; the import gate refuses gracefully).
+ */
+export declare function checkPathContained(rootAbs: string, rootReal: string, entry: string): Promise<PathContainmentCheck>;
 export declare function formatScanReport(result: SkillScanResult): string;
 export declare function formatBatchReport(results: SkillScanResult[]): string;
 export {};

package/dist/lib/skill-scanner.js

@@ -528,6 +528,34 @@ export async function scanSkillsWithCoverage(dir, declaredPaths) {
     // Starting from `rootAbs` also keeps undeclared/symlinks/errors absolute
     // and consistent with the gate's realpath expectations.
     await walk(rootAbs);
+    // FU-5 (F3 residual): a declared dir whose lowercased path maps to MORE
+    // THAN ONE distinct real on-disk dir is ambiguous. Declared-dir
+    // membership is lowercased on both sides (R1-F2-N1), so a case-colliding
+    // TWIN (declared `skills/alpha` + on-disk siblings `skills/alpha` and
+    // `skills/Alpha` on a case-sensitive FS) passes membership for BOTH
+    // dirs — neither SKILL.md lands in `undeclared` — while the declared
+    // scan below reads only one of them; the other would install un-scanned.
+    // Surface the colliding dirs as a refusal-class condition (the gate
+    // refuses, manifest-integrity, force never lifts). A single case-folded
+    // dir (no twin) is unaffected — the two-tier lookup resolves it.
+    const dirsByLower = new Map();
+    for (const d of walkDirs) {
+        const key = d.toLowerCase();
+        const group = dirsByLower.get(key);
+        if (group) {
+            group.push(d);
+        }
+        else {
+            dirsByLower.set(key, [d]);
+        }
+    }
+    const ambiguousDeclaredDirs = [];
+    for (const [key, group] of dirsByLower) {
+        if (group.length > 1 && declaredDirAbsLower.has(key)) {
+            // Sorted for deterministic output (readdir order is OS-dependent).
+            ambiguousDeclaredDirs.push(...[...group].sort());
+        }
+    }
     // Content-scanned results for declared entries only (JD-005), in declared
     // order so reports are deterministic. A declared file that is a symlink is
     // already in `symlinks` — reading through it would escape the tree (JD-003),
@@ -561,7 +589,7 @@ export async function scanSkillsWithCoverage(dir, declaredPaths) {
             continue;
         declared.push(await scanSkillFile(file));
     }
-    return { declared, undeclared, symlinks, errors };
+    return { declared, undeclared, symlinks, errors, ambiguousDeclaredDirs };
 }
 /**
  * Resolve the on-disk skill file for a declared skill directory. The coverage
@@ -597,17 +625,25 @@ async function declaredSkillFileOnDisk(absDir) {
     return canonical;
 }
 /**
- * Resolve a declared skill entry to an absolute directory and verify it stays
- * inside the scan root — both lexically (`../../x`, absolute paths) and by
- * realpath, so an in-tree symlink cannot redirect the declared read outside the
- * staged clone (JD-003). Throws when the entry escapes; the caller denies.
+ * Containment core (R2-002) — the ONE implementation of the lexical +
+ * realpath containment policy (JD-003): an entry must stay inside the root
+ * both lexically (`../../x`, absolute paths) and by realpath, so an in-tree
+ * symlink cannot redirect a read outside the staged clone. Realpath
+ * resolution is best-effort: a missing declared dir has no realpath yet, in
+ * which case lexical containment is the whole guard (the coverage walk later
+ * reports it as a missing/unscannable declared skill).
+ *
+ * Two surfaces wrap this core with their own error shapes (both bound by
+ * tests — keep the messages distinct): {@link resolveContained} (throwing;
+ * used by the coverage walk) and `skillPathContained` in agent-skills.ts
+ * (non-throwing `{ ok, reason }`; the import gate refuses gracefully).
  */
-async function resolveContained(rootAbs, rootReal, entry) {
+export async function checkPathContained(rootAbs, rootReal, entry) {
     const entryAbs = path.resolve(rootAbs, entry);
     // Lexical containment — catches `../outside` and absolute entries.
     const rel = path.relative(rootAbs, entryAbs);
     if (rel.startsWith("..") || path.isAbsolute(rel)) {
-        throw new Error(`skillguard: declared skill path escapes scan root — ${entry}`);
+        return { ok: false, entryAbs, violation: "lexical" };
     }
     // Realpath containment — catches a directory inside the tree whose real
     // location is outside it. A missing declared dir (later `unscannable`) has
@@ -617,13 +653,27 @@ async function resolveContained(rootAbs, rootReal, entry) {
         real = await fs.realpath(entryAbs);
     }
     catch {
-        return entryAbs;
+        return { ok: true, entryAbs };
     }
     const relReal = path.relative(rootReal, real);
     if (relReal.startsWith("..") || path.isAbsolute(relReal)) {
+        return { ok: false, entryAbs, violation: "realpath" };
+    }
+    return { ok: true, entryAbs };
+}
+/**
+ * Resolve a declared skill entry to an absolute directory and verify it stays
+ * inside the scan root — both lexically (`../../x`, absolute paths) and by
+ * realpath, so an in-tree symlink cannot redirect the declared read outside the
+ * staged clone (JD-003). Throws when the entry escapes; the caller denies.
+ * Thin throwing surface over the shared containment core (R2-002).
+ */
+async function resolveContained(rootAbs, rootReal, entry) {
+    const check = await checkPathContained(rootAbs, rootReal, entry);
+    if (!check.ok) {
         throw new Error(`skillguard: declared skill path escapes scan root — ${entry}`);
     }
-    return entryAbs;
+    return check.entryAbs;
 }
 // =============================================================================
 // Report formatting

package/dist/ui/AutoSkills.js

@@ -24,10 +24,20 @@ export default function AutoSkills({ projectDir, skillsDir, dryRun, force = fals
             force,
         })
             .then((r) => {
+            // FU-1 (R4-002): a refused batch (gate-blocked skills) must exit
+            // non-zero so scripted consumers can tell a refusal from success;
+            // `process.exitCode` (not `process.exit`) keeps Ink rendering.
+            // A clean run resets to 0 so an interactive re-scan (r) after a
+            // refusal can still exit 0. Force-lifted unscannable installs are
+            // NOT blocked — they keep exit 0.
+            process.exitCode = r.blocked.length > 0 ? 1 : 0;
             setResult(r);
             setLoading(false);
         })
             .catch((e) => {
+            // A scan throw is a gate deny (D7) — nothing was copied; exit
+            // non-zero like any other refusal.
+            process.exitCode = 1;
             setError(String(e));
             setLoading(false);
         });

package/dist/ui/Plugin.js

@@ -106,7 +106,7 @@ export default function Plugin({ action, target, dryRun, codex = false, force =
                             });
                             break;
                         }
-                        await runPluginImport(target, dryRun, onStep, force);
+                        await runPluginImport(target, dryRun, onStep, { force });
                         break;
                     case "export-skills":
                         if (target === "global") {

package/package.json

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