javi-forge 1.9.0 → 1.10.0

package/dist/cli/dispatch/ci.js

@@ -11,7 +11,49 @@ import { render } from "ink";
 import React from "react";
 import CI from "../../ui/CI.js";
 import { CIProvider as CIContextProvider } from "../../ui/CIContext.js";
+import { CI_HELP_TEXT } from "../help.js";
 export async function handleCi(cli, ctx) {
+    // Per-command help: `javi-forge ci --help` shows ci-specific usage, not the
+    // global banner (autoHelp is disabled at the entrypoint).
+    if (cli.flags.help === true) {
+        console.log(CI_HELP_TEXT);
+        process.exit(0);
+    }
+    // Sub-command: javi-forge ci validate → dry config validation, no execution.
+    if (cli.input[1] === "validate") {
+        const { validateCIConfig } = await import("../../commands/ci-validate.js");
+        const result = await validateCIConfig(process.cwd(), cli.flags.config || undefined);
+        if (result.ok) {
+            if (result.mode === "auto-detect") {
+                if (cli.flags.json) {
+                    console.log(JSON.stringify({ ok: true, mode: "auto-detect", runners: [] }, null, 2));
+                }
+                else {
+                    console.log("✓ No .javi-forge/ci.yaml — auto-detect mode (no config to validate)");
+                }
+            }
+            else if (cli.flags.json) {
+                console.log(JSON.stringify({ ok: true, runners: result.runners }, null, 2));
+            }
+            else {
+                console.log(`✓ CI config valid: ${result.configPath}`);
+                console.log(`  ${result.runners.length} runner(s):`);
+                for (const runner of result.runners) {
+                    console.log(`    - ${runner.name} (${runner.stack})`);
+                }
+            }
+            process.exit(0);
+        }
+        if (cli.flags.json) {
+            console.log(JSON.stringify({ ok: false, errors: result.errors }, null, 2));
+        }
+        else {
+            for (const err of result.errors) {
+                console.error(`${err.path}: ${err.message}`);
+            }
+        }
+        process.exit(1);
+    }
     // Sub-command: javi-forge ci init → install git hooks
     if (cli.input[1] === "init") {
         const { installCIHooks } = await import("../../commands/ci.js");
@@ -36,6 +78,12 @@ export async function handleCi(cli, ctx) {
         }
         process.exit(errors.length > 0 ? 1 : 0);
     }
+    // Any other positional is an unknown subcommand — show ci usage, don't run
+    // the pipeline against a typo.
+    if (cli.input[1] !== undefined) {
+        console.log(CI_HELP_TEXT);
+        process.exit(1);
+    }
     const ciMode = cli.flags.detect
         ? "detect"
         : cli.flags.shell

package/dist/cli/help.d.ts

@@ -8,8 +8,19 @@
  * 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    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 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    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";
 export declare const FLAGS_SCHEMA: {
+    readonly help: {
+        readonly type: "boolean";
+        readonly shortFlag: "h";
+        readonly default: false;
+    };
     readonly dryRun: {
         readonly type: "boolean";
         readonly default: false;

package/dist/cli/help.js

@@ -15,6 +15,8 @@ export const HELP_TEXT = `
   Commands
     init              Bootstrap a new project (default)
     ci                Run CI simulation (lint + compile + test + security + ghagga)
+    ci validate       Validate .javi-forge/ci.yaml without running anything
+    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)
     analyze           Run repoforge skills analysis
@@ -99,12 +101,52 @@ export const HELP_TEXT = `
     $ javi-forge ci --no-docker
     $ javi-forge ci --shell
     $ javi-forge ci --config .javi-forge/ci.yaml
+    $ javi-forge ci validate
+    $ javi-forge ci --help
     $ javi-forge analyze
     $ javi-forge doctor
     $ javi-forge plugin add mapbox/agent-skills
     $ javi-forge plugin list
 `;
+/**
+ * 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 const CI_HELP_TEXT = `
+  Usage
+    $ javi-forge ci [subcommand] [options]
+
+    Run a local CI simulation (lint + compile + test + security + ghagga).
+    With no subcommand, the full pipeline runs.
+
+  Subcommands
+    init            Install git hooks that call javi-forge ci
+    validate        Validate .javi-forge/ci.yaml without running anything
+
+  Options
+    --quick         Lint + compile only (fast, for pre-commit)
+    --no-docker     Run commands natively (no Docker)
+    --no-security   Skip Semgrep security scan
+    --no-ci-ghagga  Skip GHAGGA review
+    --force         (ci init) Overwrite a foreign or modified hook (backs up first)
+    --config PATH   Load ordered CI runners from a versioned config file
+                    (default discovery: .javi-forge/ci.yaml)
+    --stack STACK   Force a single explicit stack (single-stack repos only)
+    --json          (ci validate) Emit the result as JSON
+    --help          Show this help
+
+  Examples
+    $ javi-forge ci
+    $ javi-forge ci --quick
+    $ javi-forge ci validate
+    $ javi-forge ci validate --json
+    $ javi-forge ci init --force
+`;
 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).
+    help: { type: "boolean", shortFlag: "h", default: false },
     dryRun: { type: "boolean", default: false },
     stack: { type: "string", default: "" },
     ci: { type: "string", default: "" },

package/dist/commands/ci-validate.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `javi-forge ci validate` — dry validation of `.javi-forge/ci.yaml`.
+ *
+ * Pure parse-and-report over the existing validator (src/lib/ci-config.ts):
+ * resolve the config path (same discovery `runCI` uses), call `loadCIConfig`,
+ * and return a structured result. It NEVER builds images, runs Docker, or
+ * executes any phase — the CLI surface stops BEFORE execution.
+ */
+import { type CIConfigValidationError } from "../lib/ci-config.js";
+/** One validated runner, reduced to what the report shows. */
+export interface CIValidateRunnerSummary {
+    name: string;
+    stack: string;
+}
+export interface CIValidateOk {
+    ok: true;
+    /**
+     * "config" — a config file was found and validated.
+     * "auto-detect" — no config exists and none was explicitly requested, so
+     * `runCI` would use its zero-config single-runner auto-detect path
+     * (ci.ts:396-406). There is nothing to validate, and that is valid.
+     */
+    mode: "config" | "auto-detect";
+    /** Resolved config path, or null in auto-detect mode. */
+    configPath: string | null;
+    runners: CIValidateRunnerSummary[];
+}
+export interface CIValidateErr {
+    ok: false;
+    /** Resolved path we looked at, or null when discovery found nothing. */
+    configPath: string | null;
+    errors: CIConfigValidationError[];
+}
+export type CIValidateResult = CIValidateOk | CIValidateErr;
+/**
+ * Validate a project's CI config without executing anything.
+ *
+ * @param projectDir Project root to discover `.javi-forge/ci.yaml` in.
+ * @param config Optional explicit config path (from `--config`).
+ */
+export declare function validateCIConfig(projectDir: string, config?: string): Promise<CIValidateResult>;
+//# sourceMappingURL=ci-validate.d.ts.map

package/dist/commands/ci-validate.js

@@ -0,0 +1,61 @@
+/**
+ * `javi-forge ci validate` — dry validation of `.javi-forge/ci.yaml`.
+ *
+ * Pure parse-and-report over the existing validator (src/lib/ci-config.ts):
+ * resolve the config path (same discovery `runCI` uses), call `loadCIConfig`,
+ * and return a structured result. It NEVER builds images, runs Docker, or
+ * executes any phase — the CLI surface stops BEFORE execution.
+ */
+import fs from "fs-extra";
+import { CIConfigError, findCIConfig, loadCIConfig, } from "../lib/ci-config.js";
+/**
+ * Validate a project's CI config without executing anything.
+ *
+ * @param projectDir Project root to discover `.javi-forge/ci.yaml` in.
+ * @param config Optional explicit config path (from `--config`).
+ */
+export async function validateCIConfig(projectDir, config) {
+    // Discriminator: was a config path explicitly requested (`--config`)?
+    //   - explicit path that is missing → ERROR (the user asserted a file that
+    //     isn't there).
+    //   - discovery finds nothing → VALID auto-detect: `runCI` runs fine in this
+    //     exact state via its zero-config single-runner path (ci.ts:396-406), so
+    //     there is nothing to validate and that is not a failure.
+    let configPath;
+    if (config) {
+        if (!(await fs.pathExists(config))) {
+            return {
+                ok: false,
+                configPath: config,
+                errors: [{ path: config, message: `no CI config found at ${config}` }],
+            };
+        }
+        configPath = config;
+    }
+    else {
+        const discovered = await findCIConfig(projectDir);
+        if (!discovered) {
+            return { ok: true, mode: "auto-detect", configPath: null, runners: [] };
+        }
+        configPath = discovered;
+    }
+    try {
+        const ciConfig = await loadCIConfig(configPath);
+        return {
+            ok: true,
+            mode: "config",
+            configPath,
+            runners: ciConfig.runners.map((r) => ({
+                name: r.name,
+                stack: r.stack,
+            })),
+        };
+    }
+    catch (e) {
+        if (e instanceof CIConfigError) {
+            return { ok: false, configPath, errors: e.errors };
+        }
+        throw e;
+    }
+}
+//# sourceMappingURL=ci-validate.js.map

package/dist/commands/ci.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { constants } from "node:fs";
+import fsp from "node:fs/promises";
 import path from "node:path";
 import fs from "fs-extra";
 import { HOOK_ASSETS_DIR } from "../constants.js";
@@ -284,13 +285,21 @@ async function isGhaggaAvailable() {
 function report(onStep, id, label, status, detail) {
     onStep({ id, label, status, detail });
 }
-/** Detect-step label: legacy format for auto, explicit otherwise. */
+/**
+ * Detect-step label: legacy format for auto, explicit otherwise.
+ *
+ * INVARIANT (holds for every `ResolvedRunners` value): `runners` is never
+ * empty. The config path rejects an empty list before resolving
+ * (`src/lib/ci-config.ts` — "runners is required and must be a non-empty
+ * list"), and the `auto` and `stack-override` paths each yield exactly one
+ * runner. `runners[0]` therefore needs no fallback.
+ */
 function describeRunners(resolved) {
     const first = resolved.runners[0];
-    if (resolved.source === "auto" && first) {
+    if (resolved.source === "auto") {
         return `Stack: ${first.stack} (${first.buildTool})`;
     }
-    if (resolved.source === "stack-override" && first) {
+    if (resolved.source === "stack-override") {
         return `Stack: ${first.stack} (${first.buildTool}, --stack override)`;
     }
     const summary = resolved.runners
@@ -317,14 +326,16 @@ export async function runCI(options, onStep) {
     }
     // Legacy single-runner view for the zero-config auto path. Keeping this
     // shape guarantees single-stack repositories behave exactly as before.
+    // `runners[0]` is always present — see the invariant on `describeRunners`.
+    // The command lists CAN be empty, so those keep their `?? null`.
     const primary = resolved.runners[0];
     const stackInfo = {
-        stackType: primary?.stack ?? "node",
-        buildTool: primary?.buildTool ?? "npm",
-        javaVersion: primary?.javaVersion ?? "21",
-        lintCmd: primary?.lintCmds[0] ?? null,
-        compileCmd: primary?.compileCmds[0] ?? null,
-        testCmd: primary?.testCmds[0] ?? null,
+        stackType: primary.stack,
+        buildTool: primary.buildTool,
+        javaVersion: primary.javaVersion,
+        lintCmd: primary.lintCmds[0] ?? null,
+        compileCmd: primary.compileCmds[0] ?? null,
+        testCmd: primary.testCmds[0] ?? null,
     };
     // ── Detect mode ─────────────────────────────────────────────────────────────
     if (mode === "detect")
@@ -876,7 +887,16 @@ async function backupHook(hookPath) {
             }
             throw new Error(`could not write the backup ${candidate} (${errorCode(copyErr) || "unknown error"}): ${copyErr instanceof Error ? copyErr.message : String(copyErr)}. The hook was left unchanged.`);
         }
-        await fs.chmod(candidate, original.mode);
+        // The mode restore addresses the FD of the file THIS call just created,
+        // not the path: a symlink planted at `candidate` after the
+        // `COPYFILE_EXCL` copy cannot capture the mode change (SEC-1).
+        const handle = await fsp.open(candidate, constants.O_RDONLY | O_NOFOLLOW);
+        try {
+            await handle.chmod(original.mode);
+        }
+        finally {
+            await handle.close();
+        }
         return candidate;
     }
     throw new Error(`could not back up ${hookPath}: every candidate backup path is taken. The hook was left unchanged.`);
@@ -900,13 +920,51 @@ function assertHookManifestEntry(entry, hookName) {
         ? `has no "${hookName}" entry`
         : typeof entry.sha256 !== "string" ||
             typeof entry.version !== "number" ||
-            !Array.isArray(entry.historical)
-            ? `has a malformed "${hookName}" entry (expected version:number, sha256:string, historical:array)`
+            !Array.isArray(entry.historical) ||
+            !entry.historical.every((h) => typeof h?.sha256 === "string")
+            ? `has a malformed "${hookName}" entry (expected version:number, sha256:string, historical:array of {sha256:string})`
             : "";
     if (problem !== "") {
         throw new Error(`${MANIFEST_PATH} ${problem}. The javi-forge install is incomplete; ${REINSTALL_REMEDY}.`);
     }
 }
+/**
+ * `O_NOFOLLOW` on the platforms that have it, a no-op flag elsewhere. Windows
+ * has no such flag AND no hook-symlink threat worth the crash of an
+ * `undefined` in a bitmask.
+ */
+const O_NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+/**
+ * Write the hook through a FILE DESCRIPTOR, never through the path (SEC-1).
+ *
+ * `classifyHookPath` established moments earlier that `hookPath` is a regular
+ * file, but a local attacker with write access to `.git/hooks` could swap a
+ * symlink in during that window and turn the write into an arbitrary-write
+ * primitive. `O_NOFOLLOW` closes it: if the path IS a symlink when the write
+ * finally happens, `open` fails with `ELOOP` and the hook surfaces as a named
+ * per-hook error instead of clobbering the link target. Everything after the
+ * open then addresses the FD — `fchmod`, not a second path lookup — so the
+ * bytes and the mode provably land on the same inode.
+ *
+ * The mode argument applies ONLY when the file is CREATED: overwriting an
+ * existing 0644 hook would leave it non-executable and git would silently skip
+ * it. The `fchmod` is therefore unconditional, on every write path, which also
+ * makes the final mode independent of the umask.
+ *
+ * NOT covered (deferred by decision in SEC-1): a hardlink to a victim file
+ * survives `O_NOFOLLOW`. On modern Linux `fs.protected_hardlinks=1` blocks the
+ * cross-owner case; an `nlink > 1` refusal is parked in the backlog.
+ */
+async function writeHookFile(hookPath, content) {
+    const handle = await fsp.open(hookPath, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | O_NOFOLLOW, HOOK_MODE);
+    try {
+        await handle.writeFile(content, "utf8");
+        await handle.chmod(HOOK_MODE);
+    }
+    finally {
+        await handle.close();
+    }
+}
 /**
  * Bring an already-current hook back to mode 0755 WITHOUT writing bytes.
  *
@@ -997,14 +1055,7 @@ export async function installCIHooks(projectDir, options = {}) {
                 backups.push(await backupHook(hookPath));
             }
             const body = await readHookBody(name);
-            // The `mode` option applies ONLY when the file is CREATED: overwriting
-            // an existing 0644 hook would leave it non-executable and git would
-            // silently skip it. The chmod is therefore unconditional, on every
-            // write path, which also makes the mode independent of the umask.
-            await fs.writeFile(hookPath, renderHook(body, name, entry), {
-                mode: HOOK_MODE,
-            });
-            await fs.chmod(hookPath, HOOK_MODE);
+            await writeHookFile(hookPath, renderHook(body, name, entry));
             // `upgraded` means "javi-forge content was replaced by newer
             // javi-forge content". A forced overwrite of someone else's file is a
             // fresh install, not an upgrade.

package/dist/index.js

@@ -17,8 +17,17 @@ setupUpdateNotifier(pkg);
 const cli = meow(HELP_TEXT, {
     importMeta: import.meta,
     flags: FLAGS_SCHEMA,
+    // Handle --help manually so `ci --help` can show ci-specific usage instead
+    // of the global banner (meow's autoHelp would print + exit before dispatch).
+    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") {
+    console.log(HELP_TEXT);
+    process.exit(0);
+}
 const isCI = detectCI(cli.flags);
 const inkStdin = createInkStdin();
 switch (subcommand) {

package/package.json

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