javi-forge 1.37.0 → 1.38.0

package/dist/commands/doctor.js

@@ -4,40 +4,45 @@ import { FORGE_ROOT, MODULES_DIR, PLUGINS_DIR, TEMPLATES_DIR, } from "../constan
 import { detectStack } from "../lib/common.js";
 import { refreshContextDir } from "../lib/context.js";
 import { execFileAsync } from "../lib/exec.js";
+import { resolvePlatformSupport } from "../lib/platform-support.js";
 import { listInstalledPlugins } from "../lib/plugin.js";
-/** Resolve a binary name to its full path, returns null if not found */
-async function which(bin) {
+/** Resolve a binary name to its first full path, returns null if not found. */
+async function which(bin, exec, platform) {
     try {
-        const { stdout } = await execFileAsync("which", [bin]);
-        return stdout.trim() || null;
+        const command = platform === "win32" ? "where.exe" : "which";
+        const { stdout } = await exec(command, [bin]);
+        return (stdout
+            .split(/\r?\n/)
+            .map((entry) => entry.trim())
+            .find(Boolean) ?? null);
     }
     catch {
         return null;
     }
 }
 /** Read the forge manifest from a project directory */
-async function readManifest(projectDir) {
+async function readManifest(projectDir, filesystem) {
     const manifestPath = path.join(projectDir, ".javi-forge", "manifest.json");
-    if (!(await fs.pathExists(manifestPath)))
+    if (!(await filesystem.pathExists(manifestPath)))
         return null;
     try {
-        return (await fs.readJson(manifestPath));
+        return (await filesystem.readJson(manifestPath));
     }
     catch {
         return null;
     }
 }
 /** Count entries in a directory */
-async function countDir(dir) {
-    if (!(await fs.pathExists(dir)))
+async function countDir(dir, filesystem) {
+    if (!(await filesystem.pathExists(dir)))
         return 0;
-    const entries = await fs.readdir(dir);
+    const entries = await filesystem.readdir(dir);
     return entries.filter((e) => !e.startsWith(".")).length;
 }
 /** Read a single git config value, "" when unset or on any error. */
-async function gitConfigValue(cwd, key) {
+async function gitConfigValue(cwd, key, exec) {
     try {
-        const { stdout } = await execFileAsync("git", ["config", "--get", key], {
+        const { stdout } = await exec("git", ["config", "--get", key], {
             cwd,
         });
         return stdout.trim();
@@ -70,9 +75,9 @@ export function parseRemote(url) {
  * a recommendation, never a gate (a hook enforcing it was trivially bypassed
  * with `--no-verify`).
  */
-async function commitSigningCheck(cwd) {
-    const gpgSign = await gitConfigValue(cwd, "commit.gpgsign");
-    const signingKey = await gitConfigValue(cwd, "user.signingkey");
+async function commitSigningCheck(cwd, exec) {
+    const gpgSign = await gitConfigValue(cwd, "commit.gpgsign", exec);
+    const signingKey = await gitConfigValue(cwd, "user.signingkey", exec);
     if (gpgSign === "true" && signingKey) {
         return {
             label: "Commit signing",
@@ -93,8 +98,8 @@ async function commitSigningCheck(cwd) {
  * probe or protection is a non-alarming `skip` (advisory, not a failure).
  * GitLab or no `gh` → `skip` with a note to verify in the forge UI.
  */
-async function branchProtectionCheck(cwd) {
-    const remote = parseRemote(await gitConfigValue(cwd, "remote.origin.url"));
+async function branchProtectionCheck(cwd, exec, platform) {
+    const remote = parseRemote(await gitConfigValue(cwd, "remote.origin.url", exec));
     const label = "Branch protection";
     if (!remote || remote.host === "other") {
         return {
@@ -103,7 +108,7 @@ async function branchProtectionCheck(cwd) {
             detail: "no GitHub/GitLab origin — verify branch protection in the forge UI",
         };
     }
-    if (remote.host === "gitlab" || !(await which("gh"))) {
+    if (remote.host === "gitlab" || !(await which("gh", exec, platform))) {
         return {
             label,
             status: "skip",
@@ -113,14 +118,14 @@ async function branchProtectionCheck(cwd) {
     // gh + GitHub: resolve the default branch, then probe protection.
     let branch = "main";
     try {
-        const { stdout } = await execFileAsync("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], { cwd });
+        const { stdout } = await exec("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], { cwd });
         branch = stdout.trim().replace(/^origin\//, "") || "main";
     }
     catch {
         /* fall back to main */
     }
     try {
-        await execFileAsync("gh", [
+        await exec("gh", [
             "api",
             `repos/${remote.owner}/${remote.repo}/branches/${branch}/protection`,
         ]);
@@ -141,8 +146,22 @@ async function branchProtectionCheck(cwd) {
 /**
  * Run comprehensive health checks for the project and framework.
  */
-export async function runDoctor(projectDir) {
-    const cwd = projectDir ?? process.cwd();
+export async function runDoctor(projectDir, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const platformSupport = resolvePlatformSupport(platform);
+    if (platformSupport) {
+        return {
+            state: "unsupported-platform",
+            guidance: platformSupport.guidance,
+            sections: [],
+        };
+    }
+    const cwd = projectDir ?? (deps.cwd ?? process.cwd)();
+    const filesystem = deps.filesystem ?? fs;
+    const exec = deps.exec ?? execFileAsync;
+    const stackDetector = deps.stackDetector ?? detectStack;
+    const pluginLister = deps.pluginLister ?? listInstalledPlugins;
+    const contextRefresher = deps.contextRefresher ?? refreshContextDir;
     const sections = [];
     // ── 1. System Tools ────────────────────────────────────────────────────────
     const toolChecks = [];
@@ -154,12 +173,12 @@ export async function runDoctor(projectDir) {
         { name: "pnpm", label: "pnpm" },
     ];
     for (const tool of tools) {
-        const bin = await which(tool.name);
+        const bin = await which(tool.name, exec, platform);
         if (bin) {
             // Try to get version
             let version = "";
             try {
-                const { stdout } = await execFileAsync(tool.name, ["--version"]);
+                const { stdout } = await exec(tool.name, ["--version"]);
                 version = stdout.trim().split("\n")[0] ?? "";
             }
             catch {
@@ -184,8 +203,8 @@ export async function runDoctor(projectDir) {
     // L4/L6 (commit signing) and L5 (branch protection) are advisories, NOT hooks
     // (hook-consolidation D9): doctor reports, nothing blocks.
     const securityChecks = [
-        await commitSigningCheck(cwd),
-        await branchProtectionCheck(cwd),
+        await commitSigningCheck(cwd, exec),
+        await branchProtectionCheck(cwd, exec, platform),
     ];
     sections.push({ title: "Security", checks: securityChecks });
     // ── 2. Framework Structure ─────────────────────────────────────────────────
@@ -197,8 +216,8 @@ export async function runDoctor(projectDir) {
         { path: path.join(FORGE_ROOT, "ci-local"), label: "ci-local/" },
     ];
     for (const dir of expectedDirs) {
-        if (await fs.pathExists(dir.path)) {
-            const count = await countDir(dir.path);
+        if (await filesystem.pathExists(dir.path)) {
+            const count = await countDir(dir.path, filesystem);
             structureChecks.push({
                 label: dir.label,
                 status: "ok",
@@ -216,7 +235,7 @@ export async function runDoctor(projectDir) {
     sections.push({ title: "Framework Structure", checks: structureChecks });
     // ── 3. Stack Detection ─────────────────────────────────────────────────────
     const stackChecks = [];
-    const detection = await detectStack(cwd);
+    const detection = await stackDetector(cwd);
     if (detection) {
         stackChecks.push({
             label: "Detected stack",
@@ -234,7 +253,7 @@ export async function runDoctor(projectDir) {
     sections.push({ title: "Stack Detection", checks: stackChecks });
     // ── 4. Project Manifest ────────────────────────────────────────────────────
     const manifestChecks = [];
-    const manifest = await readManifest(cwd);
+    const manifest = await readManifest(cwd, filesystem);
     if (manifest) {
         manifestChecks.push({
             label: "Forge manifest",
@@ -267,7 +286,7 @@ export async function runDoctor(projectDir) {
     const moduleNames = ["engram", "obsidian-brain", "memory-simple", "ghagga"];
     for (const mod of moduleNames) {
         const modPath = path.join(cwd, ".javi-forge", "modules", mod);
-        if (await fs.pathExists(modPath)) {
+        if (await filesystem.pathExists(modPath)) {
             moduleChecks.push({ label: mod, status: "ok", detail: "installed" });
         }
         else {
@@ -281,9 +300,9 @@ export async function runDoctor(projectDir) {
     sections.push({ title: "Installed Modules", checks: moduleChecks });
     // ── 6. Plugins ─────────────────────────────────────────────────────────────
     const pluginChecks = [];
-    const pluginsDirExists = await fs.pathExists(PLUGINS_DIR);
+    const pluginsDirExists = await filesystem.pathExists(PLUGINS_DIR);
     if (pluginsDirExists) {
-        const plugins = await listInstalledPlugins();
+        const plugins = await pluginLister();
         if (plugins.length > 0) {
             for (const plugin of plugins) {
                 pluginChecks.push({
@@ -312,7 +331,7 @@ export async function runDoctor(projectDir) {
     // ── 7. Context Directory Refresh ───────────────────────────────────────────
     const contextChecks = [];
     try {
-        const result = await refreshContextDir(cwd);
+        const result = await contextRefresher(cwd);
         if (result) {
             contextChecks.push({
                 label: ".context/ refresh",
@@ -345,6 +364,6 @@ export async function runDoctor(projectDir) {
         });
     }
     sections.push({ title: "Context Directory", checks: contextChecks });
-    return { sections };
+    return { state: "supported", sections };
 }
 //# sourceMappingURL=doctor.js.map

package/dist/commands/init.d.ts

@@ -14,5 +14,8 @@ export type InitProjectResult = {
     refusalCode: string;
     platformSupport: PlatformSupport;
 };
-export declare function initProject(options: InitOptions, onStep: StepCallback): Promise<InitProjectResult>;
+export interface InitProjectDeps {
+    platform?: string;
+}
+export declare function initProject(options: InitOptions, onStep: StepCallback, deps?: InitProjectDeps): Promise<InitProjectResult>;
 //# sourceMappingURL=init.d.ts.map

package/dist/commands/init.js

@@ -16,8 +16,8 @@ import { stepMemory } from "./init/steps/memory.js";
 import { stepMock } from "./init/steps/mock.js";
 import { stepSDD } from "./init/steps/sdd.js";
 import { stepSecurityHooks } from "./init/steps/security.js";
-export async function initProject(options, onStep) {
-    const platformSupport = resolvePlatformSupport(process.platform);
+export async function initProject(options, onStep, deps = {}) {
+    const platformSupport = resolvePlatformSupport(deps.platform ?? process.platform);
     if (platformSupport) {
         return {
             ok: false,

package/dist/index.js

@@ -1,84 +1,7 @@
 #!/usr/bin/env node
-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";
-import { handleSkillsCmd } from "./cli/dispatch/skills-cmd.js";
-import { handleTdd } from "./cli/dispatch/tdd.js";
-import { handleWorkflow } from "./cli/dispatch/workflow.js";
-import { FLAGS_SCHEMA, HELP_TEXT } from "./cli/help.js";
-import { createInkStdin, detectCI, setupUpdateNotifier, } from "./cli/runtime.js";
-// Check for updates in background (non-blocking, cached 24h)
-const _require = createRequire(import.meta.url);
-const pkg = _require("../package.json");
-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` 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);
-}
-const isCI = detectCI(cli.flags);
-const inkStdin = createInkStdin();
-switch (subcommand) {
-    case "tdd": {
-        await handleTdd(cli);
-        break;
-    }
-    case "ci": {
-        await handleCi(cli, { inkStdin, isCI });
-        break;
-    }
-    case "hooks": {
-        await handleHooks(cli);
-        break;
-    }
-    case "doctor": {
-        handleDoctor(cli, { inkStdin, isCI });
-        break;
-    }
-    case "analyze": {
-        handleAnalyze(cli, { inkStdin, isCI });
-        break;
-    }
-    case "workflow": {
-        await handleWorkflow(cli);
-        break;
-    }
-    case "llms-txt": {
-        handleLlmsTxt(cli, { inkStdin, isCI });
-        break;
-    }
-    case "plugin": {
-        handlePlugin(cli, { inkStdin, isCI });
-        break;
-    }
-    case "skills": {
-        await handleSkillsCmd(cli, { inkStdin, isCI });
-        break;
-    }
-    case "skill": {
-        await handleSkillPublish(cli);
-        break;
-    }
-    case "security": {
-        await handleSecurity(cli);
-        break;
-    }
-    default: {
-        handleInitDefault(cli, { inkStdin, isCI });
-        break;
-    }
+import { bootstrapCli } from "./cli/bootstrap.js";
+const bootstrapResult = await bootstrapCli(process.platform, () => import("./cli/main.js"), (message) => console.error(message));
+if (bootstrapResult.state === "unsupported-platform") {
+    process.exitCode = bootstrapResult.exitCode;
 }
 //# sourceMappingURL=index.js.map

package/dist/lib/claude-hook-manager.d.ts

@@ -30,7 +30,6 @@ export interface ClaudeHookAssetClassification {
 }
 export interface ClaudeHookDoctorReport {
     healthy: boolean;
-    platformSupport?: PlatformSupport;
     settings: {
         state: ClaudeHookComponentState;
         version?: number;
@@ -73,6 +72,12 @@ export interface ClaudeHookDoctorReport {
      */
     nodeOnPath: NodeOnPathProbe;
 }
+export interface ClaudeHookDoctorRefusal {
+    state: "unsupported-platform";
+    healthy: false;
+    platformSupport: PlatformSupport;
+}
+export type ClaudeHookDoctorResult = ClaudeHookDoctorReport | ClaudeHookDoctorRefusal;
 /**
  * Classify the asset into one of nine states from observed bytes only. Never
  * trusts a claimed hash: the full-file SHA is always recomputed and compared to
@@ -158,8 +163,8 @@ export interface ManagedSettingsPaths {
     file: string;
     dropInDir: string;
 }
-/** Static managed-settings locations per OS (no fs). WSL reports `linux`. */
-export declare function resolveManagedSettingsPaths(platform: NodeJS.Platform): ManagedSettingsPaths;
+/** Static managed-settings locations for supported hosts only (no fs). */
+export declare function resolveManagedSettingsPaths(platform: NodeJS.Platform): ManagedSettingsPaths | null;
 /**
  * Probe one settings source path for the two documented hook-neutralizing
  * flags. Fail-closed: only a genuinely-absent path or a cleanly-parsed source
@@ -210,7 +215,7 @@ export declare function doctorClaudePreToolUse(projectDir: string, options?: {
     /** Injectable read-only ACL capability probe (defaults to the real one). */
     aclProbe?: () => Promise<AclCapability>;
     platform?: NodeJS.Platform;
-}): Promise<ClaudeHookDoctorReport>;
+}): Promise<ClaudeHookDoctorResult>;
 interface ClaudeHookMutationResultWithReport {
     ok: boolean;
     changed: string[];
@@ -257,9 +262,9 @@ export interface ClaudeHookRunDeps {
 export declare function _run(projectDir: string, mode: "install" | "repair", options: {
     force?: boolean;
 }, deps: ClaudeHookRunDeps): Promise<ClaudeHookMutationResult>;
-export declare function installClaudePreToolUse(projectDir: string): Promise<ClaudeHookMutationResult>;
+export declare function installClaudePreToolUse(projectDir: string, deps?: ClaudeHookRunDeps): Promise<ClaudeHookMutationResult>;
 export declare function repairClaudePreToolUse(projectDir: string, options?: {
     force?: boolean;
-}): Promise<ClaudeHookMutationResult>;
+}, deps?: ClaudeHookRunDeps): Promise<ClaudeHookMutationResult>;
 export {};
 //# sourceMappingURL=claude-hook-manager.d.ts.map

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

@@ -258,15 +258,8 @@ export async function probeNodeOnPath(spawn = defaultNodeSpawn) {
     }
     return { status: "resolved", version: banner, major: Number(match[1]) };
 }
-/** Static managed-settings locations per OS (no fs). WSL reports `linux`. */
+/** Static managed-settings locations for supported hosts only (no fs). */
 export function resolveManagedSettingsPaths(platform) {
-    if (platform === "darwin") {
-        const base = "/Library/Application Support/ClaudeCode";
-        return {
-            file: `${base}/managed-settings.json`,
-            dropInDir: `${base}/managed-settings.d`,
-        };
-    }
     if (platform === "win32") {
         const base = "C:\\Program Files\\ClaudeCode";
         return {
@@ -274,6 +267,8 @@ export function resolveManagedSettingsPaths(platform) {
             dropInDir: `${base}\\managed-settings.d`,
         };
     }
+    if (platform !== "linux")
+        return null;
     const base = "/etc/claude-code";
     return {
         file: `${base}/managed-settings.json`,
@@ -379,10 +374,10 @@ export async function probeExecution(projectDir, componentStates, env = {}) {
     const homeDir = env.homeDir ?? os.homedir();
     const processEnv = env.env ?? process.env;
     const resolved = resolveManagedSettingsPaths(platform);
-    const managedFile = env.managedFile !== undefined ? env.managedFile : resolved.file;
+    const managedFile = env.managedFile !== undefined ? env.managedFile : resolved?.file;
     const dropInDir = env.managedDropInDir !== undefined
         ? env.managedDropInDir
-        : resolved.dropInDir;
+        : resolved?.dropInDir;
     const specs = [
         {
             label: "project",
@@ -485,6 +480,14 @@ export async function probeExecution(projectDir, componentStates, env = {}) {
  * The `execution` verdict is INDEPENDENT of `healthy`.
  */
 export async function doctorClaudePreToolUse(projectDir, options) {
+    const platformSupport = resolvePlatformSupport(options?.platform ?? process.platform);
+    if (platformSupport) {
+        return {
+            state: "unsupported-platform",
+            healthy: false,
+            platformSupport,
+        };
+    }
     const manifest = options?.manifest ?? (await readManifest());
     const currentAssetSha = manifest.asset.sha256;
     const asset = await classifyAssetState(path.join(projectDir, ".claude", "hooks", ASSET_NAME), manifest);
@@ -538,9 +541,7 @@ export async function doctorClaudePreToolUse(projectDir, options) {
         execution.blockers.some((blocker) => blocker.startsWith("guard:"))) {
         remediation.add(aclRemediation);
     }
-    const platformSupport = resolvePlatformSupport(options?.platform ?? process.platform);
     return {
-        ...(platformSupport ? { platformSupport } : {}),
         healthy,
         settings: {
             state: settings.state,
@@ -740,11 +741,17 @@ export async function _run(projectDir, mode, options, deps) {
     // report, so the run never spawns `node --version` twice and the warning, the
     // report row and the verdict can never disagree about the same PATH.
     const nodeOnPath = await (deps.nodeProbe ?? probeNodeOnPath)();
-    const doctor = () => doctorFn(projectDir, {
-        manifest,
-        aclProbe: deps.aclProbe,
-        execution: { nodeProbe: async () => nodeOnPath },
-    });
+    const doctor = async () => {
+        const result = await doctorFn(projectDir, {
+            manifest,
+            aclProbe: deps.aclProbe,
+            execution: { nodeProbe: async () => nodeOnPath },
+        });
+        if ("state" in result) {
+            throw new Error("supported Claude lifecycle received unsupported doctor result");
+        }
+        return result;
+    };
     // Non-blocking runtime notice, computed once and carried by EVERY outcome
     // (success, no-op and refusal alike) — it never gates the mutation.
     const warnings = nodeOnPathWarnings(nodeOnPath);
@@ -832,10 +839,10 @@ export async function _run(projectDir, mode, options, deps) {
         report: await doctor(),
     };
 }
-export function installClaudePreToolUse(projectDir) {
-    return _run(projectDir, "install", {}, {});
+export function installClaudePreToolUse(projectDir, deps = {}) {
+    return _run(projectDir, "install", {}, deps);
 }
-export function repairClaudePreToolUse(projectDir, options) {
-    return _run(projectDir, "repair", options ?? {}, {});
+export function repairClaudePreToolUse(projectDir, options, deps = {}) {
+    return _run(projectDir, "repair", options ?? {}, deps);
 }
 //# sourceMappingURL=claude-hook-manager.js.map

package/dist/lib/codex-hook-manager.d.ts

@@ -102,7 +102,6 @@ export declare function classifyCodexHooksJson(value: unknown, expectedCommand:
 export type CodexTrustState = "trusted" | "untrusted";
 export interface CodexHookDoctorReport {
     healthy: boolean;
-    platformSupport?: PlatformSupport;
     hooksJson: {
         state: ClaudeHookComponentState;
         detail?: string;
@@ -128,6 +127,12 @@ export interface CodexHookDoctorReport {
     };
     remediation: string[];
 }
+export interface CodexHookDoctorRefusal {
+    state: "unsupported-platform";
+    healthy: false;
+    platformSupport: PlatformSupport;
+}
+export type CodexHookDoctorResult = CodexHookDoctorReport | CodexHookDoctorRefusal;
 export interface CodexDoctorOptions {
     platform?: NodeJS.Platform;
     manifest?: Manifest;
@@ -135,7 +140,7 @@ export interface CodexDoctorOptions {
     nodeVersion?: string;
     nodeProbe?: () => Promise<NodeOnPathProbe>;
 }
-export declare function doctorCodexPreToolUse(homeDir?: string, options?: CodexDoctorOptions): Promise<CodexHookDoctorReport>;
+export declare function doctorCodexPreToolUse(homeDir?: string, options?: CodexDoctorOptions): Promise<CodexHookDoctorResult>;
 interface CodexHookMutationResultWithReport {
     ok: boolean;
     changed: string[];
@@ -158,6 +163,7 @@ interface CodexHookLifecycleRefusal {
 }
 export type CodexHookMutationResult = CodexHookMutationResultWithReport | CodexHookLifecycleRefusal;
 export interface CodexHookRunDeps {
+    homeDirProvider?: () => string;
     secureFs?: PlatformSecureFs | null;
     clock?: () => Date;
     nonce?: () => string;
@@ -171,8 +177,8 @@ export interface CodexHookRunDeps {
 export declare function _runCodex(homeDir: string, _mode: "install" | "repair", _options: {
     force?: boolean;
 }, deps: CodexHookRunDeps): Promise<CodexHookMutationResult>;
-export declare function installCodexPreToolUse(homeDir?: string): Promise<CodexHookMutationResult>;
+export declare function installCodexPreToolUse(homeDir?: string, deps?: CodexHookRunDeps): Promise<CodexHookMutationResult>;
 export declare function repairCodexPreToolUse(homeDir?: string, options?: {
     force?: boolean;
-}): Promise<CodexHookMutationResult>;
+}, deps?: CodexHookRunDeps): Promise<CodexHookMutationResult>;
 //# sourceMappingURL=codex-hook-manager.d.ts.map

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

@@ -295,10 +295,19 @@ async function readManifest() {
         throw new Error(`unreadable claude-hooks manifest: ${read.reason}`);
     return JSON.parse(read.content);
 }
-export async function doctorCodexPreToolUse(homeDir = os.homedir(), options = {}) {
+export async function doctorCodexPreToolUse(homeDir, options = {}) {
+    const platformSupport = resolvePlatformSupport(options.platform ?? process.platform);
+    if (platformSupport) {
+        return {
+            state: "unsupported-platform",
+            healthy: false,
+            platformSupport,
+        };
+    }
+    const resolvedHomeDir = homeDir ?? os.homedir();
     const manifest = options.manifest ?? (await readManifest());
     const assetPath = options.assetPath ?? SHIPPED_CODEX_ASSET;
-    const { hooksFile, configFile } = codexConfigPaths(homeDir);
+    const { hooksFile, configFile } = codexConfigPaths(resolvedHomeDir);
     const expectedCommand = expectedCodexCommand(assetPath);
     // hooks.json registration.
     const hooksRead = await readText(hooksFile);
@@ -373,9 +382,7 @@ export async function doctorCodexPreToolUse(homeDir = os.homedir(), options = {}
     }
     if (!node.satisfiesMinimum)
         remediation.push("install Node 22 or newer");
-    const platformSupport = resolvePlatformSupport(options.platform ?? process.platform);
     return {
-        ...(platformSupport ? { platformSupport } : {}),
         healthy: status === "runnable",
         hooksJson,
         config: { featuresHooks, readable: configReadable },
@@ -421,11 +428,17 @@ export async function _runCodex(homeDir, _mode, _options, deps) {
     const { codexDir, hooksFile, configFile } = codexConfigPaths(homeDir);
     const expectedCommand = expectedCodexCommand(assetPath);
     const nodeOnPath = await (deps.nodeProbe ?? probeNodeOnPath)();
-    const doctor = () => doctorFn(homeDir, {
-        manifest,
-        assetPath,
-        nodeProbe: async () => nodeOnPath,
-    });
+    const doctor = async () => {
+        const result = await doctorFn(homeDir, {
+            manifest,
+            assetPath,
+            nodeProbe: async () => nodeOnPath,
+        });
+        if ("state" in result) {
+            throw new Error("supported Codex lifecycle received unsupported doctor result");
+        }
+        return result;
+    };
     if (!secureFs) {
         return {
             ok: false,
@@ -537,10 +550,28 @@ export async function _runCodex(homeDir, _mode, _options, deps) {
         report: await doctor(),
     };
 }
-export function installCodexPreToolUse(homeDir = os.homedir()) {
-    return _runCodex(homeDir, "install", {}, {});
+function unsupportedCodexLifecycle(platformSupport) {
+    return {
+        ok: false,
+        changed: [],
+        backups: [],
+        errors: [platformSupport.refusalCode],
+        warnings: [platformSupport.guidance],
+        lifecycleRefusal: platformSupport,
+    };
+}
+export function installCodexPreToolUse(homeDir, deps = {}) {
+    const platformSupport = resolvePlatformSupport(deps.platform ?? process.platform);
+    if (platformSupport)
+        return Promise.resolve(unsupportedCodexLifecycle(platformSupport));
+    const resolvedHomeDir = homeDir ?? (deps.homeDirProvider ?? os.homedir)();
+    return _runCodex(resolvedHomeDir, "install", {}, deps);
 }
-export function repairCodexPreToolUse(homeDir = os.homedir(), options) {
-    return _runCodex(homeDir, "repair", options ?? {}, {});
+export function repairCodexPreToolUse(homeDir, options, deps = {}) {
+    const platformSupport = resolvePlatformSupport(deps.platform ?? process.platform);
+    if (platformSupport)
+        return Promise.resolve(unsupportedCodexLifecycle(platformSupport));
+    const resolvedHomeDir = homeDir ?? (deps.homeDirProvider ?? os.homedir)();
+    return _runCodex(resolvedHomeDir, "repair", options ?? {}, deps);
 }
 //# sourceMappingURL=codex-hook-manager.js.map

package/dist/lib/platform-support.d.ts

@@ -1,19 +1,23 @@
-export declare const PLATFORM_SUPPORT_STATE: {
-    readonly MACOS_DEPRECATED: "macos-deprecated";
-};
-export declare const LIFECYCLE_SUPPORT: {
-    readonly UNSUPPORTED: "unsupported";
-};
-export declare const PLATFORM_REFUSAL: {
-    readonly MACOS_LIFECYCLE_UNSUPPORTED: "macos-lifecycle-unsupported";
+export declare const HOST_SUPPORT_STATE: {
+    readonly SUPPORTED: "supported";
+    readonly UNSUPPORTED: "unsupported-platform";
 };
+export declare const HOST_SUPPORT_GUIDANCE = "javi-forge supports Linux and Windows only.";
+export type SupportedHostPlatform = "linux" | "win32";
+export interface SupportedHost {
+    state: typeof HOST_SUPPORT_STATE.SUPPORTED;
+    platform: SupportedHostPlatform;
+}
 export interface PlatformSupport {
-    platform: "darwin";
-    state: typeof PLATFORM_SUPPORT_STATE.MACOS_DEPRECATED;
-    lifecycle: typeof LIFECYCLE_SUPPORT.UNSUPPORTED;
-    refusalCode: typeof PLATFORM_REFUSAL.MACOS_LIFECYCLE_UNSUPPORTED;
-    guidance: string;
+    state: typeof HOST_SUPPORT_STATE.UNSUPPORTED;
+    refusalCode: typeof HOST_SUPPORT_STATE.UNSUPPORTED;
+    guidance: typeof HOST_SUPPORT_GUIDANCE;
 }
-export declare const MACOS_DEPRECATION_GUIDANCE = "macOS is deprecated and unsupported for install, repair, and init; pin a supported release or migrate. Existing installed guards are not removed; Darwin removal is planned for 2.0.";
+export type HostSupportResult = SupportedHost | PlatformSupport;
+/**
+ * Classifies every host value without aliases or fallthrough.
+ */
+export declare function classifyHostPlatform(platform: string): HostSupportResult;
+/** Returns an unsupported result for legacy callers, otherwise undefined. */
 export declare function resolvePlatformSupport(platform: string): PlatformSupport | undefined;
 //# sourceMappingURL=platform-support.d.ts.map