javi-forge 1.38.3 → 1.38.5

package/dist/cli/help.d.ts

@@ -19,7 +19,7 @@ export declare const CI_HELP_TEXT = "\n  Usage\n    $ javi-forge ci [subcommand]
  * Per-command help for `hooks`, shown by `javi-forge hooks --help` (or when
  * `hooks` is given an unknown subcommand). Whitespace is significant.
  */
-export declare const HOOKS_HELP_TEXT = "\n  Usage\n    $ javi-forge hooks run <pre-commit|pre-push>\n    $ javi-forge hooks <install|doctor|repair> claude [--force]\n\n    Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed\n    cheap\u2192expensive order, fail-fast. With no hooks: config the default is the\n    quick native CI gate (setup + lint + compile + gates \u2014 no tests, no coverage).\n\n  Subcommands\n    run pre-commit    Run the composed pre-commit sections\n    run pre-push      Run the composed pre-push sections\n    install claude    Install the managed Claude PreToolUse guard (.claude/)\n    doctor claude     Report Claude PreToolUse guard health (informational)\n    repair claude     Repair the managed guard; --force overwrites edited assets\n\n  Notes\n    A blocking section failure exits non-zero and blocks the commit/push.\n    A broken .javi-forge/ci.yaml exits 1 (fail-closed \u2014 never skips a gate).\n    To skip: git commit --no-verify   (pre-push: git push --no-verify)\n    doctor claude is informational (always exits 0); install/repair exit 0 on\n    success, non-zero on refusal/failure. Use repair claude --force to overwrite\n    a locally edited managed asset.\n    Linux: install/repair claude need the acl package (getfacl) to prove the\n    parent chain \u2014 apt install acl / apk add acl / dnf install acl. Without it\n    they refuse fail-closed; an already-installed guard keeps firing, and\n    doctor claude reports the acl capability as its own row.\n    Claude Code spawns the guard with node from ITS path, so node must resolve\n    there, not only inside javi-forge.\n\n  Examples\n    $ javi-forge hooks run pre-commit\n    $ javi-forge hooks run pre-push\n    $ javi-forge hooks install claude\n    $ javi-forge hooks doctor claude\n    $ javi-forge hooks repair claude --force\n";
+export declare const HOOKS_HELP_TEXT = "\n  Usage\n    $ javi-forge hooks run <pre-commit|pre-push>\n    $ javi-forge hooks <install|doctor|repair> <claude|codex> [--force]\n\n    Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed\n    cheap\u2192expensive order, fail-fast. With no hooks: config the default is the\n    quick native CI gate (setup + lint + compile + gates \u2014 no tests, no coverage).\n\n  Subcommands\n    run pre-commit    Run the composed pre-commit sections\n    run pre-push      Run the composed pre-push sections\n    install claude    Install the managed Claude PreToolUse guard (.claude/)\n    doctor claude     Report Claude PreToolUse guard health (informational)\n    repair claude     Repair the managed guard; --force overwrites edited assets\n    install codex     Install the managed Codex PreToolUse guard (~/.codex/)\n    doctor codex      Report Codex hook execution readiness and trust boundary\n    repair codex      Repair the managed Codex guard; --force overwrites edits\n\n  Notes\n    A blocking section failure exits non-zero and blocks the commit/push.\n    A broken .javi-forge/ci.yaml exits 1 (fail-closed \u2014 never skips a gate).\n    To skip: git commit --no-verify   (pre-push: git push --no-verify)\n    doctor claude is informational (always exits 0); install/repair exit 0 on\n    success, non-zero on refusal/failure. Use repair claude --force to overwrite\n    a locally edited managed asset.\n    doctor codex exits 0 when runnable, 1 when blocked, and 2 when inconclusive;\n    it does not prove provider trust or runtime execution. Use repair codex\n    --force only to overwrite an edited managed asset.\n    Linux: install/repair claude need the acl package (getfacl) to prove the\n    parent chain \u2014 apt install acl / apk add acl / dnf install acl. Without it\n    they refuse fail-closed; an already-installed guard keeps firing, and\n    doctor claude reports the acl capability as its own row.\n    Claude Code spawns the guard with node from ITS path, so node must resolve\n    there, not only inside javi-forge.\n\n  Examples\n    $ javi-forge hooks run pre-commit\n    $ javi-forge hooks run pre-push\n    $ javi-forge hooks install claude\n    $ javi-forge hooks doctor claude\n    $ javi-forge hooks repair claude --force\n    $ javi-forge hooks install codex\n    $ javi-forge hooks doctor codex\n    $ javi-forge hooks repair codex --force\n";
 export declare const FLAGS_SCHEMA: {
     readonly help: {
         readonly type: "boolean";

package/dist/cli/help.js

@@ -166,7 +166,7 @@ export const CI_HELP_TEXT = `
 export const HOOKS_HELP_TEXT = `
   Usage
     $ javi-forge hooks run <pre-commit|pre-push>
-    $ javi-forge hooks <install|doctor|repair> claude [--force]
+    $ javi-forge hooks <install|doctor|repair> <claude|codex> [--force]
 
     Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed
     cheap→expensive order, fail-fast. With no hooks: config the default is the
@@ -178,6 +178,9 @@ export const HOOKS_HELP_TEXT = `
     install claude    Install the managed Claude PreToolUse guard (.claude/)
     doctor claude     Report Claude PreToolUse guard health (informational)
     repair claude     Repair the managed guard; --force overwrites edited assets
+    install codex     Install the managed Codex PreToolUse guard (~/.codex/)
+    doctor codex      Report Codex hook execution readiness and trust boundary
+    repair codex      Repair the managed Codex guard; --force overwrites edits
 
   Notes
     A blocking section failure exits non-zero and blocks the commit/push.
@@ -186,6 +189,9 @@ export const HOOKS_HELP_TEXT = `
     doctor claude is informational (always exits 0); install/repair exit 0 on
     success, non-zero on refusal/failure. Use repair claude --force to overwrite
     a locally edited managed asset.
+    doctor codex exits 0 when runnable, 1 when blocked, and 2 when inconclusive;
+    it does not prove provider trust or runtime execution. Use repair codex
+    --force only to overwrite an edited managed asset.
     Linux: install/repair claude need the acl package (getfacl) to prove the
     parent chain — apt install acl / apk add acl / dnf install acl. Without it
     they refuse fail-closed; an already-installed guard keeps firing, and
@@ -199,6 +205,9 @@ export const HOOKS_HELP_TEXT = `
     $ javi-forge hooks install claude
     $ javi-forge hooks doctor claude
     $ javi-forge hooks repair claude --force
+    $ javi-forge hooks install codex
+    $ javi-forge hooks doctor codex
+    $ javi-forge hooks repair codex --force
 `;
 export const FLAGS_SCHEMA = {
     // `--help` is handled manually (autoHelp is disabled at the entrypoint so

package/dist/commands/plugin.js

@@ -62,16 +62,20 @@ export async function runPluginSearch(query, onStep) {
     const stepId = "plugin-search";
     report(onStep, stepId, `Search plugins${query ? `: ${query}` : ""}`, "running");
     const results = await searchRegistry(query);
-    if (results.length === 0) {
-        report(onStep, stepId, `Search plugins${query ? `: ${query}` : ""}`, "done", query
-            ? `no plugins matching "${query}"`
-            : "registry empty or unreachable");
+    if (results.status === "cancelled") {
+        report(onStep, stepId, `Search plugins${query ? `: ${query}` : ""}`, "error", "registry search cancelled");
+    }
+    else if (results.status === "unavailable") {
+        report(onStep, stepId, `Search plugins${query ? `: ${query}` : ""}`, "error", "registry unavailable");
+    }
+    else if (results.entries.length === 0) {
+        report(onStep, stepId, `Search plugins${query ? `: ${query}` : ""}`, "done", query ? `no plugins matching "${query}"` : "registry empty");
     }
     else {
-        const summary = results
+        const summary = results.entries
             .map((p) => `${p.id} — ${p.description}`)
             .join("\n  ");
-        report(onStep, stepId, `Search plugins${query ? `: ${query}` : ""}`, "done", `${results.length} results:\n  ${summary}`);
+        report(onStep, stepId, `Search plugins${query ? `: ${query}` : ""}`, "done", `${results.entries.length} results:\n  ${summary}`);
     }
 }
 /**

package/dist/lib/codex-hook-manager.js

@@ -254,9 +254,10 @@ function buildCodexHooksContainer(assetPath) {
     };
 }
 /**
- * Merge our managed group into an existing container: drop any prior managed
- * groups (ours, by command regex) and append a fresh one, preserving every
- * foreign group. A fresh install (no container) yields the clean container.
+ * Merge our managed group into an existing container: remove only prior managed
+ * handlers (ours, by command regex), preserve foreign handlers in their groups,
+ * and append one fresh canonical managed group. A fresh install (no container)
+ * yields the clean container.
  */
 function mergeCodexHooks(existing, assetPath) {
     if (!isPlainObject(existing))
@@ -266,14 +267,24 @@ function mergeCodexHooks(existing, assetPath) {
         container.hooks = {};
     const hooks = container.hooks;
     const groups = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
-    const kept = groups.filter((group) => {
-        const list = isPlainObject(group) && Array.isArray(group.hooks) ? group.hooks : [];
-        const isOurs = list.some((h) => isPlainObject(h) &&
+    const kept = [];
+    for (const group of groups) {
+        if (!isPlainObject(group) || !Array.isArray(group.hooks)) {
+            kept.push(group);
+            continue;
+        }
+        const foreign = group.hooks.filter((h) => !(isPlainObject(h) &&
             h.type === "command" &&
             typeof h.command === "string" &&
-            CODEX_CMD_RE.test(h.command));
-        return !isOurs;
-    });
+            CODEX_CMD_RE.test(h.command)));
+        if (foreign.length === 0)
+            continue;
+        if (foreign.length === group.hooks.length) {
+            kept.push(group);
+            continue;
+        }
+        kept.push({ ...group, hooks: foreign });
+    }
     const fresh = buildCodexHooksContainer(assetPath).hooks;
     hooks.PreToolUse = [...kept, ...fresh.PreToolUse];
     return container;
@@ -372,7 +383,9 @@ export async function doctorCodexPreToolUse(homeDir, options = {}) {
             ? "inconclusive"
             : "runnable";
     const remediation = [];
-    if (hooksJson.state === "absent" || asset.state !== "managed-current") {
+    if (hooksJson.state === "absent" ||
+        hooksJson.state === "released-outdated" ||
+        asset.state !== "managed-current") {
         remediation.push("install the codex guard with: javi-forge hooks install codex");
     }
     if (!trusted)

package/dist/lib/plugin.d.ts

@@ -1,4 +1,12 @@
 import type { InstalledPlugin, PluginRegistryEntry, PluginSyncResult, PluginValidationResult } from "../types/index.js";
+export type RegistrySearchResult = {
+    status: "success";
+    entries: PluginRegistryEntry[];
+} | {
+    status: "unavailable";
+} | {
+    status: "cancelled";
+};
 /**
  * Validate a plugin directory structure and manifest.
  */
@@ -38,8 +46,14 @@ export declare function removePlugin(name: string, options?: {
 export declare function listInstalledPlugins(): Promise<InstalledPlugin[]>;
 /**
  * Fetch the remote plugin registry and optionally filter by query.
+ *
+ * A registry that cannot be read or validated is deliberately distinct from a
+ * valid registry with no matches. Callers need that distinction to avoid
+ * presenting a network failure as a successful empty search.
  */
-export declare function searchRegistry(query?: string): Promise<PluginRegistryEntry[]>;
+export declare function searchRegistry(query?: string, options?: {
+    signal?: AbortSignal;
+}): Promise<RegistrySearchResult>;
 /**
  * Detect installed plugins in a project's .javi-forge/plugins/ directory.
  * Returns an array of plugin names (sorted alphabetically).

package/dist/lib/plugin.js

@@ -8,6 +8,7 @@ import { evaluateCoverageGate, scanFailureMessage, } from "./skill-install-gate.
 import { scanSkillsWithCoverage } from "./skill-scanner.js";
 const KEBAB_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const REGISTRY_REQUEST_TIMEOUT_MS = 10_000;
 // ── Validation ──────────────────────────────────────────────────────────────
 /**
  * Validate a plugin directory structure and manifest.
@@ -251,26 +252,90 @@ export async function listInstalledPlugins() {
 }
 /**
  * Fetch the remote plugin registry and optionally filter by query.
+ *
+ * A registry that cannot be read or validated is deliberately distinct from a
+ * valid registry with no matches. Callers need that distinction to avoid
+ * presenting a network failure as a successful empty search.
  */
-export async function searchRegistry(query) {
+export async function searchRegistry(query, options = {}) {
+    const { signal: callerSignal } = options;
+    if (callerSignal?.aborted)
+        return { status: "cancelled" };
+    const controller = new AbortController();
+    let timedOut = false;
+    let callerCancelled = false;
+    let resolveDeadline;
+    const deadline = new Promise((resolve) => {
+        resolveDeadline = resolve;
+    });
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+        resolveDeadline();
+    }, REGISTRY_REQUEST_TIMEOUT_MS);
+    const cancelFromCaller = () => {
+        callerCancelled = true;
+        controller.abort();
+        resolveDeadline();
+    };
+    callerSignal?.addEventListener("abort", cancelFromCaller, { once: true });
     try {
-        const response = await fetch(PLUGIN_REGISTRY_URL);
-        if (!response.ok) {
-            return [];
-        }
-        const registry = (await response.json());
-        let plugins = registry.plugins ?? [];
-        if (query) {
-            const q = query.toLowerCase();
-            plugins = plugins.filter((p) => p.id.toLowerCase().includes(q) ||
-                p.description.toLowerCase().includes(q) ||
-                p.tags.some((t) => t.toLowerCase().includes(q)));
-        }
-        return plugins;
+        const response = await Promise.race([
+            Promise.resolve().then(() => fetch(PLUGIN_REGISTRY_URL, { signal: controller.signal })),
+            deadline,
+        ]);
+        if (callerCancelled || callerSignal?.aborted)
+            return { status: "cancelled" };
+        if (timedOut || !response || !response.ok)
+            return { status: "unavailable" };
+        const body = await Promise.race([response.json(), deadline]);
+        if (callerCancelled || callerSignal?.aborted)
+            return { status: "cancelled" };
+        if (timedOut || !isPluginRegistry(body))
+            return { status: "unavailable" };
+        const entries = query
+            ? filterRegistryEntries(body.plugins, query)
+            : body.plugins;
+        return { status: "success", entries };
     }
     catch {
-        return [];
+        return callerCancelled || callerSignal?.aborted
+            ? { status: "cancelled" }
+            : { status: "unavailable" };
     }
+    finally {
+        clearTimeout(timeout);
+        callerSignal?.removeEventListener("abort", cancelFromCaller);
+    }
+}
+function filterRegistryEntries(plugins, query) {
+    const normalizedQuery = query.toLowerCase();
+    return plugins.filter((plugin) => plugin.id.toLowerCase().includes(normalizedQuery) ||
+        plugin.description.toLowerCase().includes(normalizedQuery) ||
+        plugin.tags.some((tag) => tag.toLowerCase().includes(normalizedQuery)));
+}
+function isPluginRegistry(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.version === "string" &&
+        typeof value.updatedAt === "string" &&
+        Array.isArray(value.plugins) &&
+        value.plugins.every(isPluginRegistryEntry));
+}
+function isPluginRegistryEntry(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.id === "string" &&
+        typeof value.repository === "string" &&
+        typeof value.description === "string" &&
+        Array.isArray(value.tags) &&
+        value.tags.every((tag) => typeof tag === "string") &&
+        (value.stars === undefined ||
+            (typeof value.stars === "number" && Number.isFinite(value.stars))) &&
+        (value.updatedAt === undefined || typeof value.updatedAt === "string"));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
 }
 // ── Sync ───────────────────────────────────────────────────────────────
 /**

package/package.json

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