javi-forge 1.22.2 → 1.23.0

package/dist/cli/dispatch/hooks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `javi-forge hooks` handler — console-only (no Ink; a git hook runs in a
+ * terminal git owns). Mirrors the `ci init` branch: the command module
+ * (`./commands/hooks.js`) is lazy-imported inside the handler to keep cold-start
+ * minimal, because hooks are on the commit/push hot path.
+ *
+ * Only subcommand: `hooks run <pre-commit|pre-push>` → dispatches to runHook and
+ * exits with its code. Any other subcommand or a missing name → usage + exit 1.
+ */
+import type { CLI } from "./types.js";
+export declare function handleHooks(cli: CLI): Promise<void>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/cli/dispatch/hooks.js

@@ -0,0 +1,31 @@
+/**
+ * `javi-forge hooks` handler — console-only (no Ink; a git hook runs in a
+ * terminal git owns). Mirrors the `ci init` branch: the command module
+ * (`./commands/hooks.js`) is lazy-imported inside the handler to keep cold-start
+ * minimal, because hooks are on the commit/push hot path.
+ *
+ * Only subcommand: `hooks run <pre-commit|pre-push>` → dispatches to runHook and
+ * exits with its code. Any other subcommand or a missing name → usage + exit 1.
+ */
+import { HOOKS_HELP_TEXT } from "../help.js";
+export async function handleHooks(cli) {
+    if (cli.flags.help === true) {
+        console.log(HOOKS_HELP_TEXT);
+        process.exit(0);
+    }
+    if (cli.input[1] === "run") {
+        const name = cli.input[2];
+        if (name === undefined) {
+            console.error("Usage: javi-forge hooks run <pre-commit|pre-push>");
+            process.exit(1);
+        }
+        const { runHook } = await import("../../commands/hooks.js");
+        const code = await runHook(name, process.cwd());
+        process.exit(code);
+    }
+    // No subcommand → show usage (exit 0). An unknown subcommand is a typo →
+    // show usage but exit 1 rather than run nothing silently.
+    console.log(HOOKS_HELP_TEXT);
+    process.exit(cli.input[1] === undefined ? 0 : 1);
+}
+//# sourceMappingURL=hooks.js.map

package/dist/cli/help.d.ts

@@ -8,13 +8,18 @@
  * Help banner shown by meow when `--help` is passed or invalid args are supplied.
  * Multi-line template literal — preserve exact formatting (whitespace is significant).
  */
-export declare const HELP_TEXT = "\n  Usage\n    $ javi-forge [command] [options]\n\n  Commands\n    init              Bootstrap a new project (default)\n    ci                Run CI simulation (lint + compile + test + security + ghagga)\n    ci validate       Validate .javi-forge/ci.yaml without running anything\n    ci init           Install git hooks that call javi-forge ci\n    tdd init          Install TDD-enforcing pre-commit hook (auto-detects stack)\n    tdd pipeline      Install TDD pipeline pre-push hook (--mode strict|warn)\n    analyze           Run repoforge skills analysis\n    doctor            Show health report\n    workflow show     Render a workflow graph as ASCII (--template <name> or file path)\n    workflow validate Validate project state against a workflow graph\n    workflow list     List available workflows and built-in templates\n    plugin add        Install a plugin from GitHub (org/repo)\n    plugin remove     Remove an installed plugin\n    plugin list       List installed plugins\n    plugin search     Search the plugin registry\n    plugin validate   Validate a local plugin directory\n    plugin sync       Auto-detect and wire installed plugins\n    plugin export     Export plugin to Agent Skills spec format (skills.json)\n    plugin export     --codex: Export plugin to Codex-compatible TOML subagent files\n    plugin export-skills  Generate aggregated skills.json from all installed plugins\n    plugin export-skills global  Generate global skills.json from all globally installed plugins\n    plugin import     Import an Agent Skills spec package as a javi-forge plugin\n    skills doctor     Show skills health report (add --deep for conflict detection)\n    skills budget     Show token cost of loaded skills (add -b N for custom budget)\n    skills score      Score a skill on quality dimensions (completeness, clarity, testability, token-efficiency)\n    skills benchmark  Benchmark a skill with structural quality checks\n    skills auto       Auto-detect project stack and suggest/install matching AI skills\n    skills auto-install  Alias for skills auto\n    skill publish     Package a skill directory for marketplace distribution (generates plugin.json)\n    security baseline   Create security baseline from current audit findings\n    security check      Check for regressions against baseline (exits non-zero if found)\n    security update     Re-snapshot baseline (acknowledge current vulns)\n    security allowlist  Add all current findings to the allowlist (suppress in future checks)\n    llms-txt          Generate AI-friendly llms.txt for current project\n\n  Options\n    --dry-run       Preview changes without writing files\n    --stack         Project stack (node, python, go, rust, java-gradle, java-maven, elixir)\n    --ci            CI provider (github, gitlab, woodpecker)\n    --memory        Memory module (engram, obsidian-brain, memory-simple, none)\n    --project-name  Project name (skips name prompt)\n    --ghagga        Enable GHAGGA review system\n    --mock          Enable mock-first mode (no real API keys needed)\n    --local-ai      Include local AI dev stack (Ollama + Docker Compose)\n    --batch         Non-interactive mode (auto-proceed, no keyboard input)\n    --deep          Enable deep analysis (conflict + duplicate detection)\n    --budget, -b    Token budget limit for skills (default: 8000)\n    --skills-dir    Custom skills directory path\n    --author        Author name for skill publish\n    --repo          Repository URL for skill publish\n    --version       Show version\n    --help          Show this help\n\n  CI options (javi-forge ci)\n    --quick         Lint + compile only (fast, for pre-commit)\n    --shell         Open interactive shell in CI container\n    --detect        Show detected stack and exit\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only \u2014\n                    insufficient for hybrid repos; use --config instead)\n    --no-docker     Run commands natively (no Docker)\n    --no-ci-ghagga  Skip GHAGGA review\n    --no-security   Skip Semgrep security scan\n    --timeout N     Per-step timeout in seconds (default: 600)\n\n  CI hooks (javi-forge ci init)\n    Install git hooks that call javi-forge ci.\n    No files copied \u2014 hooks reference the global CLI.\n    Existing hooks javi-forge did not write are refused, never clobbered.\n    --force         Overwrite a foreign or locally modified hook. The previous\n                    content is copied to a .bak sibling first; if that backup\n                    cannot be written, the hook is left untouched. Symlinked\n                    hook paths are refused even with --force.\n\n  Examples\n    $ javi-forge\n    $ javi-forge init --dry-run\n    $ javi-forge init --stack node --ci github\n    $ javi-forge ci\n    $ javi-forge ci init\n    $ javi-forge ci init --force\n    $ javi-forge tdd init\n    $ javi-forge ci --quick\n    $ javi-forge ci --no-ci-ghagga --no-security\n    $ javi-forge ci --no-docker\n    $ javi-forge ci --shell\n    $ javi-forge ci --config .javi-forge/ci.yaml\n    $ javi-forge ci validate\n    $ javi-forge ci --help\n    $ javi-forge analyze\n    $ javi-forge doctor\n    $ javi-forge plugin add mapbox/agent-skills\n    $ javi-forge plugin list\n";
+export declare const HELP_TEXT = "\n  Usage\n    $ javi-forge [command] [options]\n\n  Commands\n    init              Bootstrap a new project (default)\n    ci                Run CI simulation (lint + compile + test + security + ghagga)\n    ci validate       Validate .javi-forge/ci.yaml without running anything\n    ci init           Install git hooks that call javi-forge ci\n    tdd init          Install TDD-enforcing pre-commit hook (auto-detects stack)\n    tdd pipeline      Install TDD pipeline pre-push hook (--mode strict|warn)\n    hooks run         Run a git hook's composed sections (pre-commit | pre-push)\n    analyze           Run repoforge skills analysis\n    doctor            Show health report\n    workflow show     Render a workflow graph as ASCII (--template <name> or file path)\n    workflow validate Validate project state against a workflow graph\n    workflow list     List available workflows and built-in templates\n    plugin add        Install a plugin from GitHub (org/repo)\n    plugin remove     Remove an installed plugin\n    plugin list       List installed plugins\n    plugin search     Search the plugin registry\n    plugin validate   Validate a local plugin directory\n    plugin sync       Auto-detect and wire installed plugins\n    plugin export     Export plugin to Agent Skills spec format (skills.json)\n    plugin export     --codex: Export plugin to Codex-compatible TOML subagent files\n    plugin export-skills  Generate aggregated skills.json from all installed plugins\n    plugin export-skills global  Generate global skills.json from all globally installed plugins\n    plugin import     Import an Agent Skills spec package as a javi-forge plugin\n    skills doctor     Show skills health report (add --deep for conflict detection)\n    skills budget     Show token cost of loaded skills (add -b N for custom budget)\n    skills score      Score a skill on quality dimensions (completeness, clarity, testability, token-efficiency)\n    skills benchmark  Benchmark a skill with structural quality checks\n    skills auto       Auto-detect project stack and suggest/install matching AI skills\n    skills auto-install  Alias for skills auto\n    skill publish     Package a skill directory for marketplace distribution (generates plugin.json)\n    security baseline   Create security baseline from current audit findings\n    security check      Check for regressions against baseline (exits non-zero if found)\n    security update     Re-snapshot baseline (acknowledge current vulns)\n    security allowlist  Add all current findings to the allowlist (suppress in future checks)\n    llms-txt          Generate AI-friendly llms.txt for current project\n\n  Options\n    --dry-run       Preview changes without writing files\n    --stack         Project stack (node, python, go, rust, java-gradle, java-maven, elixir)\n    --ci            CI provider (github, gitlab, woodpecker)\n    --memory        Memory module (engram, obsidian-brain, memory-simple, none)\n    --project-name  Project name (skips name prompt)\n    --ghagga        Enable GHAGGA review system\n    --mock          Enable mock-first mode (no real API keys needed)\n    --local-ai      Include local AI dev stack (Ollama + Docker Compose)\n    --batch         Non-interactive mode (auto-proceed, no keyboard input)\n    --deep          Enable deep analysis (conflict + duplicate detection)\n    --budget, -b    Token budget limit for skills (default: 8000)\n    --skills-dir    Custom skills directory path\n    --author        Author name for skill publish\n    --repo          Repository URL for skill publish\n    --version       Show version\n    --help          Show this help\n\n  CI options (javi-forge ci)\n    --quick         Lint + compile only (fast, for pre-commit)\n    --shell         Open interactive shell in CI container\n    --detect        Show detected stack and exit\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only \u2014\n                    insufficient for hybrid repos; use --config instead)\n    --no-docker     Run commands natively (no Docker)\n    --no-ci-ghagga  Skip GHAGGA review\n    --no-security   Skip Semgrep security scan\n    --timeout N     Per-step timeout in seconds (default: 600)\n\n  CI hooks (javi-forge ci init)\n    Install git hooks that call javi-forge ci.\n    No files copied \u2014 hooks reference the global CLI.\n    Existing hooks javi-forge did not write are refused, never clobbered.\n    --force         Overwrite a foreign or locally modified hook. The previous\n                    content is copied to a .bak sibling first; if that backup\n                    cannot be written, the hook is left untouched. Symlinked\n                    hook paths are refused even with --force.\n\n  Examples\n    $ javi-forge\n    $ javi-forge init --dry-run\n    $ javi-forge init --stack node --ci github\n    $ javi-forge ci\n    $ javi-forge ci init\n    $ javi-forge ci init --force\n    $ javi-forge tdd init\n    $ javi-forge ci --quick\n    $ javi-forge ci --no-ci-ghagga --no-security\n    $ javi-forge ci --no-docker\n    $ javi-forge ci --shell\n    $ javi-forge ci --config .javi-forge/ci.yaml\n    $ javi-forge ci validate\n    $ javi-forge ci --help\n    $ javi-forge analyze\n    $ javi-forge doctor\n    $ javi-forge plugin add mapbox/agent-skills\n    $ javi-forge plugin list\n";
 /**
  * Per-command help for `ci`, shown by `javi-forge ci --help` (or when `ci` is
  * given an unknown subcommand). Kept consistent with the global HELP_TEXT
  * layout — whitespace is significant.
  */
 export declare const CI_HELP_TEXT = "\n  Usage\n    $ javi-forge ci [subcommand] [options]\n\n    Run a local CI simulation (lint + compile + test + security + ghagga).\n    With no subcommand, the full pipeline runs.\n\n  Subcommands\n    init            Install git hooks that call javi-forge ci\n    validate        Validate .javi-forge/ci.yaml without running anything\n\n  Options\n    --quick         Lint + compile only (fast, for pre-commit)\n    --no-docker     Run commands natively (no Docker)\n    --no-security   Skip Semgrep security scan\n    --no-ci-ghagga  Skip GHAGGA review\n    --force         (ci init) Overwrite a foreign or modified hook (backs up first)\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only)\n    --json          (ci validate) Emit the result as JSON\n    --help          Show this help\n\n  Examples\n    $ javi-forge ci\n    $ javi-forge ci --quick\n    $ javi-forge ci validate\n    $ javi-forge ci validate --json\n    $ javi-forge ci init --force\n";
+/**
+ * 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\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\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\n  Examples\n    $ javi-forge hooks run pre-commit\n    $ javi-forge hooks run pre-push\n";
 export declare const FLAGS_SCHEMA: {
     readonly help: {
         readonly type: "boolean";

package/dist/cli/help.js

@@ -19,6 +19,7 @@ export const HELP_TEXT = `
     ci init           Install git hooks that call javi-forge ci
     tdd init          Install TDD-enforcing pre-commit hook (auto-detects stack)
     tdd pipeline      Install TDD pipeline pre-push hook (--mode strict|warn)
+    hooks run         Run a git hook's composed sections (pre-commit | pre-push)
     analyze           Run repoforge skills analysis
     doctor            Show health report
     workflow show     Render a workflow graph as ASCII (--template <name> or file path)
@@ -143,6 +144,31 @@ export const CI_HELP_TEXT = `
     $ javi-forge ci validate --json
     $ javi-forge ci init --force
 `;
+/**
+ * Per-command help for `hooks`, shown by `javi-forge hooks --help` (or when
+ * `hooks` is given an unknown subcommand). Whitespace is significant.
+ */
+export const HOOKS_HELP_TEXT = `
+  Usage
+    $ javi-forge hooks run <pre-commit|pre-push>
+
+    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
+    quick native CI gate (setup + lint + compile + gates — no tests, no coverage).
+
+  Subcommands
+    run pre-commit  Run the composed pre-commit sections
+    run pre-push    Run the composed pre-push sections
+
+  Notes
+    A blocking section failure exits non-zero and blocks the commit/push.
+    A broken .javi-forge/ci.yaml exits 1 (fail-closed — never skips a gate).
+    To skip: git commit --no-verify   (pre-push: git push --no-verify)
+
+  Examples
+    $ javi-forge hooks run pre-commit
+    $ javi-forge hooks run pre-push
+`;
 export const FLAGS_SCHEMA = {
     // `--help` is handled manually (autoHelp is disabled at the entrypoint so
     // `ci --help` can show ci-specific usage instead of the global banner).

package/dist/commands/hooks.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `javi-forge hooks run <name>` dispatcher (hook-consolidation S1a).
+ *
+ * Pure logic, no Ink: composes the ENABLED sections for a hook from the
+ * `hooks:` section of `.javi-forge/ci.yaml`, in a fixed cheap→expensive order,
+ * and runs them fail-fast. A blocking section failure exits non-zero; only an
+ * advisory section (pre-push `tdd: "warn"`) prints and continues.
+ *
+ * Fail-closed: a missing config means the default `[ci]` composition (today's
+ * behavior); a config that FAILS to validate exits 1 — a broken config never
+ * silently skips a gate.
+ *
+ * S1a scope: only the `ci` section has a body. The tdd/secrets/permissions/deps
+ * sections have no factory yet (they land in S3/S4); an enabled-but-unregistered
+ * feature is skipped by `composeSections` until its slice wires a factory.
+ */
+import { type CIHooksConfig } from "../lib/ci-config.js";
+import { runCI } from "./ci.js";
+/** A single composable unit of hook work. */
+export interface HookSection {
+    /** stable id — "secrets" | "permissions" | "tdd" | "deps" | "ci" */
+    id: string;
+    /** false ONLY for an advisory section (pre-push tdd:"warn") */
+    blocking: boolean;
+    run(ctx: {
+        projectDir: string;
+    }): Promise<{
+        ok: boolean;
+        detail?: string;
+    }>;
+}
+export type SectionId = "secrets" | "permissions" | "tdd" | "deps" | "ci";
+export type SectionFactory = () => HookSection;
+export type SectionRegistry = Partial<Record<SectionId, SectionFactory>>;
+export type HookName = "pre-commit" | "pre-push";
+/**
+ * Compose the enabled, implemented sections for a hook in fixed order. The
+ * section's blocking flag is derived from config (so pre-push tdd:"warn" is
+ * advisory) regardless of the factory's own default. An enabled feature with no
+ * registered factory is skipped — the S1a gate for tdd/security bodies that land
+ * in later slices.
+ */
+export declare function composeSections(name: HookName, config: CIHooksConfig | null, registry: SectionRegistry): HookSection[];
+/** Resolve the parsed `hooks:` config for a project (null → default [ci]). */
+export declare function loadHooksConfig(projectDir: string): Promise<CIHooksConfig | null>;
+/** Injectable seams for tests; every field defaults to the real implementation. */
+export interface RunHookDeps {
+    loadConfig?: (projectDir: string) => Promise<CIHooksConfig | null>;
+    registry?: SectionRegistry;
+    runCIImpl?: typeof runCI;
+    log?: (msg: string) => void;
+    logError?: (msg: string) => void;
+}
+/**
+ * Run the composed sections for `name`. Returns the process exit code:
+ * 0 iff every blocking section passed. Fail-fast on the first blocking failure;
+ * fail-closed (exit 1) on an unknown hook name or an unparseable config.
+ */
+export declare function runHook(name: string, projectDir: string, deps?: RunHookDeps): Promise<number>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/commands/hooks.js

@@ -0,0 +1,169 @@
+/**
+ * `javi-forge hooks run <name>` dispatcher (hook-consolidation S1a).
+ *
+ * Pure logic, no Ink: composes the ENABLED sections for a hook from the
+ * `hooks:` section of `.javi-forge/ci.yaml`, in a fixed cheap→expensive order,
+ * and runs them fail-fast. A blocking section failure exits non-zero; only an
+ * advisory section (pre-push `tdd: "warn"`) prints and continues.
+ *
+ * Fail-closed: a missing config means the default `[ci]` composition (today's
+ * behavior); a config that FAILS to validate exits 1 — a broken config never
+ * silently skips a gate.
+ *
+ * S1a scope: only the `ci` section has a body. The tdd/secrets/permissions/deps
+ * sections have no factory yet (they land in S3/S4); an enabled-but-unregistered
+ * feature is skipped by `composeSections` until its slice wires a factory.
+ */
+import { findCIConfig, loadCIConfig, } from "../lib/ci-config.js";
+import { runCI } from "./ci.js";
+/** Fixed cheap→expensive order per hook (deterministic is a feature). */
+const PRE_COMMIT_ORDER = ["secrets", "permissions", "tdd", "ci"];
+const PRE_PUSH_ORDER = ["deps", "tdd", "ci"];
+/** No config / no `hooks:` section → the [ci]-only default (byte-for-byte today). */
+const DEFAULT_HOOKS = {
+    preCommit: { ci: true, tdd: false, secrets: false, permissions: false },
+    prePush: { ci: true, tdd: false, deps: false },
+};
+function featureState(id, name, config) {
+    if (name === "pre-commit") {
+        const pc = config.preCommit;
+        switch (id) {
+            case "secrets":
+                return { enabled: pc.secrets, blocking: true };
+            case "permissions":
+                return { enabled: pc.permissions, blocking: true };
+            case "tdd":
+                return { enabled: pc.tdd, blocking: true };
+            case "ci":
+                return { enabled: pc.ci, blocking: true };
+            default:
+                return { enabled: false, blocking: true };
+        }
+    }
+    const pp = config.prePush;
+    switch (id) {
+        case "deps":
+            return { enabled: pp.deps, blocking: true };
+        case "tdd":
+            // "warn" is advisory (never blocks); false is off; "strict"/true block.
+            return { enabled: pp.tdd !== false, blocking: pp.tdd !== "warn" };
+        case "ci":
+            return { enabled: pp.ci, blocking: true };
+        default:
+            return { enabled: false, blocking: true };
+    }
+}
+/**
+ * Compose the enabled, implemented sections for a hook in fixed order. The
+ * section's blocking flag is derived from config (so pre-push tdd:"warn" is
+ * advisory) regardless of the factory's own default. An enabled feature with no
+ * registered factory is skipped — the S1a gate for tdd/security bodies that land
+ * in later slices.
+ */
+export function composeSections(name, config, registry) {
+    const cfg = config ?? DEFAULT_HOOKS;
+    const order = name === "pre-commit" ? PRE_COMMIT_ORDER : PRE_PUSH_ORDER;
+    const sections = [];
+    for (const id of order) {
+        const state = featureState(id, name, cfg);
+        if (!state.enabled)
+            continue;
+        const factory = registry[id];
+        if (!factory)
+            continue; // S1a: enabled but not yet implemented → skip
+        const section = factory();
+        sections.push({ ...section, blocking: state.blocking });
+    }
+    return sections;
+}
+/**
+ * The `ci` section: runs the quick native CI gate IN-PROCESS (no subprocess, no
+ * PATH/version skew). `runCI` throws on a blocking failure → the section reports
+ * ok:false. `quick` runs setup + lint + compile + gates — NO tests, NO coverage.
+ */
+function ciSection(runCIImpl, log) {
+    return {
+        id: "ci",
+        blocking: true,
+        async run({ projectDir }) {
+            try {
+                await runCIImpl({
+                    projectDir,
+                    mode: "quick",
+                    noDocker: true,
+                    noSecurity: true,
+                    noGhagga: true,
+                }, (step) => reportStep(step, log));
+                return { ok: true };
+            }
+            catch (e) {
+                return {
+                    ok: false,
+                    detail: e instanceof Error ? e.message : String(e),
+                };
+            }
+        },
+    };
+}
+/** Console step feedback (no Ink in a git hook). Honest — never claims tests. */
+function reportStep(step, log) {
+    if (step.status === "done")
+        log(`  ✓ ${step.label}`);
+    else if (step.status === "error")
+        log(`  ✗ ${step.label}${step.detail ? ` — ${step.detail}` : ""}`);
+    else if (step.status === "warning")
+        log(`  ⚠ ${step.label}`);
+}
+function defaultRegistry(runCIImpl, log) {
+    return { ci: () => ciSection(runCIImpl, log) };
+}
+/** Resolve the parsed `hooks:` config for a project (null → default [ci]). */
+export async function loadHooksConfig(projectDir) {
+    const configPath = await findCIConfig(projectDir);
+    if (!configPath)
+        return null;
+    // Throws CIConfigError on an invalid config → runHook maps that to exit 1.
+    const config = await loadCIConfig(configPath);
+    return config.hooks ?? null;
+}
+const USAGE = "Usage: javi-forge hooks run <pre-commit|pre-push>";
+/**
+ * Run the composed sections for `name`. Returns the process exit code:
+ * 0 iff every blocking section passed. Fail-fast on the first blocking failure;
+ * fail-closed (exit 1) on an unknown hook name or an unparseable config.
+ */
+export async function runHook(name, projectDir, deps = {}) {
+    const log = deps.log ?? ((m) => console.log(m));
+    const logError = deps.logError ?? ((m) => console.error(m));
+    if (name !== "pre-commit" && name !== "pre-push") {
+        logError(USAGE);
+        return 1;
+    }
+    const loadConfig = deps.loadConfig ?? loadHooksConfig;
+    let config;
+    try {
+        config = await loadConfig(projectDir);
+    }
+    catch (e) {
+        // Fail-closed: a broken config never silently skips a gate.
+        logError(e instanceof Error ? e.message : String(e));
+        return 1;
+    }
+    const runCIImpl = deps.runCIImpl ?? runCI;
+    const registry = deps.registry ?? defaultRegistry(runCIImpl, log);
+    const sections = composeSections(name, config, registry);
+    for (const section of sections) {
+        log(`▶ ${section.id}`);
+        const result = await section.run({ projectDir });
+        if (result.ok)
+            continue;
+        const detail = result.detail ? `: ${result.detail}` : "";
+        if (section.blocking) {
+            logError(`✗ ${section.id} failed${detail}`);
+            return 1; // fail-fast
+        }
+        log(`⚠ ${section.id} (advisory) failed${detail}`);
+    }
+    return 0;
+}
+//# sourceMappingURL=hooks.js.map

package/dist/index.js

@@ -2,6 +2,7 @@
 import { createRequire } from "node:module";
 import meow from "meow";
 import { handleCi } from "./cli/dispatch/ci.js";
+import { handleHooks } from "./cli/dispatch/hooks.js";
 import { handleSecurity } from "./cli/dispatch/security.js";
 import { handleAnalyze, handleDoctor, handleInitDefault, handleLlmsTxt, handlePlugin, } from "./cli/dispatch/simple-renderers.js";
 import { handleSkillPublish } from "./cli/dispatch/skill-publish.js";
@@ -22,9 +23,9 @@ const cli = meow(HELP_TEXT, {
     autoHelp: false,
 });
 const subcommand = cli.input[0] ?? "init";
-// Global --help: every command except `ci` shows the global banner here. `ci`
-// owns its per-command help inside handleCi.
-if (cli.flags.help && subcommand !== "ci") {
+// Global --help: every command except `ci` and `hooks` shows the global banner
+// here. Those two own their per-command help inside their handlers.
+if (cli.flags.help && subcommand !== "ci" && subcommand !== "hooks") {
     console.log(HELP_TEXT);
     process.exit(0);
 }
@@ -39,6 +40,10 @@ switch (subcommand) {
         await handleCi(cli, { inkStdin, isCI });
         break;
     }
+    case "hooks": {
+        await handleHooks(cli);
+        break;
+    }
     case "doctor": {
         handleDoctor(cli, { inkStdin, isCI });
         break;

package/dist/lib/ci-config.d.ts

@@ -74,11 +74,41 @@ export interface CIGateConfig {
      */
     timeout?: number;
 }
+/** pre-commit hook feature toggles (version 2 only). */
+export interface CIHookCommitConfig {
+    /** quick native CI gate (default true when `hooks:` is present) */
+    ci: boolean;
+    /** run the stack test command */
+    tdd: boolean;
+    /** L1 secret scan */
+    secrets: boolean;
+    /** L3 permission boundaries */
+    permissions: boolean;
+}
+/** pre-push hook feature toggles (version 2 only). */
+export interface CIHookPushConfig {
+    /** quick native CI gate (default true when `hooks:` is present) */
+    ci: boolean;
+    /** run the stack test command — false | "strict" | "warn" ("warn" = advisory) */
+    tdd: boolean | "strict" | "warn";
+    /** L2 dependency audit */
+    deps: boolean;
+}
+/**
+ * Parsed `hooks:` section. Every hook is always present with defaults applied
+ * (ci on, every other feature off) so the dispatcher never branches on absence.
+ */
+export interface CIHooksConfig {
+    preCommit: CIHookCommitConfig;
+    prePush: CIHookPushConfig;
+}
 export interface CIConfig {
     version: number;
     runners: CIRunnerConfig[];
     /** Present only under version 2 when `gates:` is declared. */
     gates?: CIGateConfig[];
+    /** Present only under version 2 when `hooks:` is declared. */
+    hooks?: CIHooksConfig;
 }
 export interface CIConfigValidationError {
     path: string;
@@ -96,6 +126,14 @@ export declare const CI_STACKS: readonly string[];
  * (the caller discards them all if `errors` is non-empty — fail closed).
  */
 export declare function validateGates(raw: unknown, errors: CIConfigValidationError[]): CIGateConfig[];
+/**
+ * Validate the `hooks:` block (version 2 only). Mirrors validateGate: every
+ * schema error names the offending field and the caller discards the whole
+ * config if `errors` is non-empty (fail closed). Always returns a fully
+ * defaulted config (ci on, every other feature off) so the dispatcher never
+ * branches on an omitted hook or feature.
+ */
+export declare function validateHooks(raw: unknown, errors: CIConfigValidationError[]): CIHooksConfig;
 /**
  * Parse and validate CI config YAML text. Throws CIConfigError listing every
  * validation problem; never returns a partially valid config.

package/dist/lib/ci-config.js

@@ -396,6 +396,113 @@ export function validateGates(raw, errors) {
     });
     return gates;
 }
+const HOOK_NAMES = new Set(["pre-commit", "pre-push"]);
+const PRE_COMMIT_FEATURES = new Set(["ci", "tdd", "secrets", "permissions"]);
+const PRE_PUSH_FEATURES = new Set(["ci", "tdd", "deps"]);
+/** Validate one boolean feature toggle, returning `dflt` when absent. */
+function validateBoolFeature(raw, key, base, errors, dflt) {
+    const value = raw[key];
+    if (value === undefined)
+        return dflt;
+    if (typeof value !== "boolean") {
+        errors.push({
+            path: `${base}.${key}`,
+            message: `${key} must be a boolean`,
+        });
+        return dflt;
+    }
+    return value;
+}
+/** Validate the tri-state pre-push.tdd toggle (false | "strict" | "warn"). */
+function validatePushTdd(value, base, errors) {
+    if (value === undefined)
+        return false;
+    if (typeof value === "boolean")
+        return value;
+    if (value === "strict" || value === "warn")
+        return value;
+    errors.push({
+        path: `${base}.tdd`,
+        message: `tdd must be a boolean or one of: strict, warn (got "${String(value)}")`,
+    });
+    return false;
+}
+/**
+ * Validate the `hooks:` block (version 2 only). Mirrors validateGate: every
+ * schema error names the offending field and the caller discards the whole
+ * config if `errors` is non-empty (fail closed). Always returns a fully
+ * defaulted config (ci on, every other feature off) so the dispatcher never
+ * branches on an omitted hook or feature.
+ */
+export function validateHooks(raw, errors) {
+    const preCommit = {
+        ci: true,
+        tdd: false,
+        secrets: false,
+        permissions: false,
+    };
+    const prePush = { ci: true, tdd: false, deps: false };
+    if (!isRecord(raw)) {
+        errors.push({
+            path: "hooks",
+            message: "hooks must be a mapping of hook names to feature toggles",
+        });
+        return { preCommit, prePush };
+    }
+    for (const key of Object.keys(raw)) {
+        if (!HOOK_NAMES.has(key)) {
+            errors.push({ path: `hooks.${key}`, message: `unknown field "${key}"` });
+        }
+    }
+    if (raw["pre-commit"] !== undefined) {
+        const pc = raw["pre-commit"];
+        const base = "hooks.pre-commit";
+        if (!isRecord(pc)) {
+            errors.push({
+                path: base,
+                message: "pre-commit must be a mapping of feature toggles",
+            });
+        }
+        else {
+            for (const key of Object.keys(pc)) {
+                if (!PRE_COMMIT_FEATURES.has(key)) {
+                    errors.push({
+                        path: `${base}.${key}`,
+                        message: `unknown field "${key}"`,
+                    });
+                }
+            }
+            preCommit.ci = validateBoolFeature(pc, "ci", base, errors, true);
+            preCommit.tdd = validateBoolFeature(pc, "tdd", base, errors, false);
+            preCommit.secrets = validateBoolFeature(pc, "secrets", base, errors, false);
+            preCommit.permissions = validateBoolFeature(pc, "permissions", base, errors, false);
+        }
+    }
+    if (raw["pre-push"] !== undefined) {
+        const pp = raw["pre-push"];
+        const base = "hooks.pre-push";
+        if (!isRecord(pp)) {
+            errors.push({
+                path: base,
+                message: "pre-push must be a mapping of feature toggles",
+            });
+        }
+        else {
+            for (const key of Object.keys(pp)) {
+                if (!PRE_PUSH_FEATURES.has(key)) {
+                    errors.push({
+                        path: `${base}.${key}`,
+                        message: `unknown field "${key}"`,
+                    });
+                }
+            }
+            prePush.ci = validateBoolFeature(pp, "ci", base, errors, true);
+            prePush.tdd = validatePushTdd(pp.tdd, base, errors);
+            prePush.deps = validateBoolFeature(pp, "deps", base, errors, false);
+        }
+    }
+    return { preCommit, prePush };
+}
 // =============================================================================
 // Public API
 // =============================================================================
@@ -434,6 +541,7 @@ export function parseCIConfig(rawYaml, source) {
     }
     const isV2 = version === 2;
     const hasGates = doc.gates !== undefined;
+    const hasHooks = doc.hooks !== undefined;
     for (const key of Object.keys(doc)) {
         if (TOP_LEVEL_FIELDS.has(key))
             continue;
@@ -445,16 +553,25 @@ export function parseCIConfig(rawYaml, source) {
             }
             continue;
         }
+        if (key === "hooks") {
+            // Same version-gating as `gates`: `hooks` is a v2-only key, so under any
+            // other version it reports a named error, not the generic unknown-field.
+            if (!isV2) {
+                errors.push({ path: "hooks", message: "hooks require version: 2" });
+            }
+            continue;
+        }
         errors.push({ path: key, message: `unknown field "${key}"` });
     }
     if (isV2) {
-        // v2: runners OPTIONAL when gates present; NEITHER runners nor gates fails
-        // closed (nothing to run).
+        // v2: runners OPTIONAL when gates OR hooks are present; declaring NONE of the
+        // three fails closed (nothing to run).
         if (!hasGates &&
+            !hasHooks &&
             (!Array.isArray(doc.runners) || doc.runners.length === 0)) {
             errors.push({
                 path: "runners",
-                message: "a version 2 config must declare runners or gates (nothing to run otherwise)",
+                message: "a version 2 config must declare runners, gates or hooks (nothing to run otherwise)",
             });
         }
     }
@@ -468,6 +585,9 @@ export function parseCIConfig(rawYaml, source) {
     // Gates are validated ONLY under v2 — a v1+gates config is already rejected
     // above and must not surface a second, confusing wave of gate-field errors.
     const gates = isV2 && hasGates ? validateGates(doc.gates, errors) : [];
+    // Hooks are validated ONLY under v2 — a v1+hooks config is already rejected
+    // above and must not surface a second wave of hook-field errors.
+    const hooks = isV2 && hasHooks ? validateHooks(doc.hooks, errors) : undefined;
     const runners = [];
     if (Array.isArray(doc.runners)) {
         doc.runners.forEach((raw, index) => {
@@ -496,6 +616,8 @@ export function parseCIConfig(rawYaml, source) {
     const config = { version: version ?? CI_CONFIG_VERSION, runners };
     if (gates.length > 0)
         config.gates = gates;
+    if (hooks)
+        config.hooks = hooks;
     return config;
 }
 /**

package/modules/engram/install-engram.sh

@@ -153,20 +153,31 @@ fi
 CHECKSUM_URL="https://github.com/${REPO}/releases/download/${VERSION}/checksums.txt"
 if curl -fsSL -o "${TMP_DIR}/checksums.txt" "$CHECKSUM_URL" 2>/dev/null; then
     echo -e "${CYAN}Verifying checksum...${NC}"
+    CHECKSUM_RAN=false
     pushd "$TMP_DIR" > /dev/null
     if command -v sha256sum &>/dev/null; then
         sha256sum -c checksums.txt --ignore-missing || {
             echo -e "${RED}Checksum verification failed!${NC}"
             exit 1
         }
+        CHECKSUM_RAN=true
     elif command -v shasum &>/dev/null; then
         shasum -a 256 -c checksums.txt --ignore-missing || {
             echo -e "${RED}Checksum verification failed!${NC}"
             exit 1
         }
+        CHECKSUM_RAN=true
     fi
     popd > /dev/null
-    echo -e "${GREEN}Checksum verified${NC}"
+    if [[ "$CHECKSUM_RAN" == "true" ]]; then
+        echo -e "${GREEN}Checksum verified${NC}"
+    elif [[ "$NO_VERIFY" == "true" ]]; then
+        echo -e "${YELLOW}WARNING: neither sha256sum nor shasum found; skipping checksum verification (--no-verify)${NC}"
+    else
+        echo -e "${RED}Error: neither sha256sum nor shasum is available. Cannot verify download integrity.${NC}"
+        echo -e "${YELLOW}Install coreutils (sha256sum) or perl (shasum), or use --no-verify to skip verification (NOT RECOMMENDED).${NC}"
+        exit 1
+    fi
 else
     if [[ "$NO_VERIFY" == "true" ]]; then
         echo -e "${YELLOW}WARNING: Skipping checksum verification (--no-verify)${NC}"

package/package.json

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

package/templates/github/ci-go.yml

@@ -34,7 +34,7 @@ concurrency:
 
 jobs:
   build:
-    uses: JNZader/javi-forge/.github/workflows/reusable-build-go.yml@main
+    uses: JNZader/javi-forge/.github/workflows/reusable-build-go.yml@667908ddb5e1aeb8e44ec65e84e4bc0e4f936d6c # main@2026-08-10
     with:
       go-version: '1.23'  # Change to: 1.22, 1.23
       run-lint: true

package/templates/github/ci-java.yml

@@ -37,7 +37,7 @@ concurrency:
 
 jobs:
   build:
-    uses: JNZader/javi-forge/.github/workflows/reusable-build-java.yml@main
+    uses: JNZader/javi-forge/.github/workflows/reusable-build-java.yml@667908ddb5e1aeb8e44ec65e84e4bc0e4f936d6c # main@2026-08-10
     with:
       java-version: '21'  # Change to your version: 17, 21, 25
       run-spotless: true

package/templates/github/ci-node.yml

@@ -34,7 +34,7 @@ concurrency:
 
 jobs:
   build:
-    uses: JNZader/javi-forge/.github/workflows/reusable-build-node.yml@main
+    uses: JNZader/javi-forge/.github/workflows/reusable-build-node.yml@667908ddb5e1aeb8e44ec65e84e4bc0e4f936d6c # main@2026-08-10
     with:
       node-version: '20'  # Change to: 18, 20, 22
       package-manager: 'npm'  # Change to: npm, yarn, pnpm

package/templates/github/ci-python.yml

@@ -34,7 +34,7 @@ concurrency:
 
 jobs:
   build:
-    uses: JNZader/javi-forge/.github/workflows/reusable-build-python.yml@main
+    uses: JNZader/javi-forge/.github/workflows/reusable-build-python.yml@667908ddb5e1aeb8e44ec65e84e4bc0e4f936d6c # main@2026-08-10
     with:
       python-version: '3.12'  # Change to: 3.10, 3.11, 3.12
       package-manager: 'pip'  # Change to: pip, poetry, uv

package/templates/github/ci-rust.yml

@@ -34,7 +34,7 @@ concurrency:
 
 jobs:
   build:
-    uses: JNZader/javi-forge/.github/workflows/reusable-build-rust.yml@main
+    uses: JNZader/javi-forge/.github/workflows/reusable-build-rust.yml@667908ddb5e1aeb8e44ec65e84e4bc0e4f936d6c # main@2026-08-10
     with:
       toolchain: 'stable'  # Change to: stable, beta, nightly
       run-clippy: true

package/templates/github/deploy-docker-zero-downtime.yml

@@ -55,10 +55,10 @@ jobs:
     outputs:
       image_tag: ${{ steps.meta.outputs.tags }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
 
       - name: Log in to Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -66,7 +66,7 @@ jobs:
 
       - name: Extract metadata
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
@@ -74,7 +74,7 @@ jobs:
             type=raw,value=latest
 
       - name: Build and push
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@ca052bb54ab0790a636c9b5f226502c73d547a25 # v5.4.0
         with:
           context: .
           push: true
@@ -88,11 +88,16 @@ jobs:
     environment: production
     steps:
       - name: Deploy via SSH + docker rollout
-        uses: appleboy/ssh-action@v1
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
+        env:
+          # Expression-injection hardening: the workflow_dispatch input is passed
+          # as an env var (never interpolated into the shell script text).
+          SERVICE: ${{ github.event.inputs.service || '__SERVICE_NAME__' }}
         with:
           host: ${{ env.DEPLOY_HOST }}
           username: ${{ env.DEPLOY_USER }}
           key: ${{ secrets.DEPLOY_KEY }}
+          envs: SERVICE
           script: |
             set -euo pipefail
 
@@ -102,7 +107,6 @@ jobs:
             docker compose pull
 
             # Zero-downtime rollout for the target service
-            SERVICE="${{ github.event.inputs.service || '__SERVICE_NAME__' }}"
             echo "::group::Rolling out ${SERVICE}"
             docker rollout "${SERVICE}"
             echo "::endgroup::"
@@ -111,15 +115,19 @@ jobs:
             docker image prune -f
 
       - name: Verify deployment
-        uses: appleboy/ssh-action@v1
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
+        env:
+          # Expression-injection hardening: the workflow_dispatch input is passed
+          # as an env var (never interpolated into the shell script text).
+          SERVICE: ${{ github.event.inputs.service || '__SERVICE_NAME__' }}
         with:
           host: ${{ env.DEPLOY_HOST }}
           username: ${{ env.DEPLOY_USER }}
           key: ${{ secrets.DEPLOY_KEY }}
+          envs: SERVICE
           script: |
             set -euo pipefail
             cd ${{ secrets.DEPLOY_DIR || '~/app' }}
-            SERVICE="${{ github.event.inputs.service || '__SERVICE_NAME__' }}"
 
             # Wait for healthcheck (max 60s)
             TIMEOUT=60

package/templates/github/ghagga-review.yml

@@ -21,7 +21,9 @@ jobs:
   review:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      # TODO(pin): ghagga has no v1 tag upstream (releases start at v2) — this
+      # ref cannot be SHA-pinned as-is; pick a real released tag and pin it.
       - uses: JNZader/ghagga@v1
         with:
           mode: simple

package/templates/local-ai/.env.example

@@ -1,17 +1,24 @@
 # Local AI Stack — Environment Variables
 # Copy to .env in your project: cp .env.example .env
+#
+# Secure defaults: all ports bind to 127.0.0.1 (loopback), WebUI auth is ON,
+# and SUPABASE_DB_PASSWORD is REQUIRED (no default) for the "full" profile.
 
 # ── Ollama ──────────────────────────────────────────────────────────────────
 OLLAMA_PORT=11434
 
 # ── Open WebUI ──────────────────────────────────────────────────────────────
 WEBUI_PORT=3000
-WEBUI_AUTH=false
+# Auth is ON by default (create the admin account on first visit).
+# Set to false ONLY if you accept an unauthenticated local UI.
+WEBUI_AUTH=true
 
 # ── n8n ─────────────────────────────────────────────────────────────────────
 N8N_PORT=5678
 
 # ── Supabase (Postgres) ────────────────────────────────────────────────────
 SUPABASE_DB_PORT=5432
-SUPABASE_DB_PASSWORD=postgres
+# CHANGE ME — required, no default (Postgres refuses to start if unset). Generate one:
+#   openssl rand -base64 24
+SUPABASE_DB_PASSWORD=
 SUPABASE_DB_NAME=app

package/templates/local-ai/docker-compose.yml

@@ -18,7 +18,9 @@ services:
     container_name: ollama
     restart: unless-stopped
     ports:
-      - "${OLLAMA_PORT:-11434}:11434"
+      # Bound to loopback by default — this is a LOCAL dev stack. To expose on
+      # your LAN, change 127.0.0.1 to your interface IP (opt-in, not default).
+      - "127.0.0.1:${OLLAMA_PORT:-11434}:11434"
     volumes:
       - ollama_data:/root/.ollama
     environment:
@@ -45,12 +47,14 @@ services:
     profiles: ["ui", "auto", "full"]
     restart: unless-stopped
     ports:
-      - "${WEBUI_PORT:-3000}:8080"
+      - "127.0.0.1:${WEBUI_PORT:-3000}:8080"
     volumes:
       - open_webui_data:/app/backend/data
     environment:
       - OLLAMA_BASE_URL=http://ollama:11434
-      - WEBUI_AUTH=${WEBUI_AUTH:-false}
+      # Auth ON by default. Set WEBUI_AUTH=false in .env only if you accept an
+      # unauthenticated UI (loopback-only mitigates, but any local process can reach it).
+      - WEBUI_AUTH=${WEBUI_AUTH:-true}
     depends_on:
       ollama:
         condition: service_healthy
@@ -62,7 +66,7 @@ services:
     profiles: ["auto", "full"]
     restart: unless-stopped
     ports:
-      - "${N8N_PORT:-5678}:5678"
+      - "127.0.0.1:${N8N_PORT:-5678}:5678"
     volumes:
       - n8n_data:/home/node/.n8n
     environment:
@@ -76,11 +80,15 @@ services:
     profiles: ["full"]
     restart: unless-stopped
     ports:
-      - "${SUPABASE_DB_PORT:-5432}:5432"
+      - "127.0.0.1:${SUPABASE_DB_PORT:-5432}:5432"
     volumes:
       - supabase_db_data:/var/lib/postgresql/data
     environment:
-      POSTGRES_PASSWORD: ${SUPABASE_DB_PASSWORD:-postgres}
+      # No insecure default — REQUIRED. If unset/empty, Postgres refuses to
+      # initialize ("superuser password is not specified"): set it in .env.
+      # Note: a compose-level `:?` guard would also break the core (ollama-only)
+      # profile at parse time, so the check is delegated to the postgres image.
+      POSTGRES_PASSWORD: ${SUPABASE_DB_PASSWORD}
       POSTGRES_DB: ${SUPABASE_DB_NAME:-app}
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U postgres"]