@ai-devkit/agent-manager 0.31.0 → 0.33.0

package/dist/readiness/AgentReadiness.js

@@ -0,0 +1,614 @@
+import { constants } from "node:fs";
+import { access as fsAccess, readFile as fsReadFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { delimiter, join } from "node:path";
+import { promisify } from "node:util";
+import { getCodexCapacityReport } from "../capacity/index.js";
+import { AGENTS } from "../utils/agents.js";
+const execFileAsync = promisify(execFile);
+const READINESS_AGENT_TYPES = [
+    "claude",
+    "codex",
+    "copilot",
+    "grok_cli",
+    "opencode",
+    "pi"
+];
+const ANSI_ESCAPE_PATTERN = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
+const AGENT_HOME_DIRS = {
+    claude: ".claude",
+    codex: ".codex",
+    copilot: ".copilot",
+    grok_cli: ".grok",
+    opencode: ".config/opencode",
+    pi: ".pi"
+};
+function runtime(options) {
+    return {
+        homeDir: options.homeDir ?? process.env.HOME ?? "",
+        path: options.path ?? process.env.PATH ?? "",
+        assetRoot: options.assetRoot ?? null,
+        builtInSkillNames: options.builtInSkillNames ?? [],
+        skillRoots: options.skillRoots ?? {},
+        readFile: options.readFile ?? ((target)=>fsReadFile(target, "utf8")),
+        access: options.access ?? ((target, mode = constants.R_OK)=>fsAccess(target, mode)),
+        runCommand: options.runCommand ?? defaultRunCommand,
+        codexAuth: options.codexAuth ?? (async ()=>(await getCodexCapacityReport()).authenticated)
+    };
+}
+async function defaultRunCommand(command, args) {
+    const result = await execFileAsync(command, args, {
+        encoding: "utf8",
+        timeout: 5000,
+        maxBuffer: 1024 * 1024
+    });
+    return {
+        stdout: result.stdout,
+        stderr: result.stderr
+    };
+}
+function statusRank(status) {
+    return status === "fail" ? 2 : status === "warn" ? 1 : 0;
+}
+export function worstReadinessStatus(statuses) {
+    return statuses.reduce((worst, current)=>statusRank(current) > statusRank(worst) ? current : worst, "pass");
+}
+function displayHome(target, homeDir) {
+    return target === homeDir ? "~" : target.startsWith(`${homeDir}/`) ? `~${target.slice(homeDir.length)}` : target;
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+async function accessible(target, rt, mode = constants.R_OK) {
+    try {
+        await rt.access(target, mode);
+        return true;
+    } catch  {
+        return false;
+    }
+}
+async function resolveExecutable(command, rt) {
+    const candidates = rt.path.split(delimiter).filter(Boolean).map((directory)=>join(directory, command));
+    const checks = await Promise.all(candidates.map(async (target)=>({
+            target,
+            available: await accessible(target, rt, constants.X_OK)
+        })));
+    return checks.find((check)=>check.available)?.target ?? null;
+}
+async function executableCheck(agent, rt) {
+    const command = AGENTS[agent].command;
+    const resolvedPath = await resolveExecutable(command, rt);
+    return {
+        command,
+        path: resolvedPath,
+        status: resolvedPath ? "pass" : "fail",
+        errors: resolvedPath ? [] : [
+            `${command} was not found on PATH`
+        ]
+    };
+}
+async function directoryCheck(agent, rt) {
+    const target = join(rt.homeDir, AGENT_HOME_DIRS[agent]);
+    const readable = await accessible(target, rt);
+    return {
+        path: displayHome(target, rt.homeDir),
+        present: readable,
+        readable,
+        status: readable ? "pass" : "fail",
+        errors: readable ? [] : [
+            "global configuration directory is unavailable"
+        ]
+    };
+}
+async function builtInSkillsCheck(agent, rt) {
+    const relativeRoot = rt.skillRoots[agent];
+    if (!relativeRoot) {
+        return {
+            path: null,
+            required: rt.builtInSkillNames.length,
+            present: 0,
+            missing: [
+                ...rt.builtInSkillNames
+            ],
+            status: "info",
+            errors: []
+        };
+    }
+    const root = join(rt.homeDir, relativeRoot);
+    const checks = await Promise.all(rt.builtInSkillNames.map(async (name)=>({
+            name,
+            present: await accessible(join(root, name, "SKILL.md"), rt)
+        })));
+    const present = checks.filter((check)=>check.present).map((check)=>check.name);
+    const missing = rt.builtInSkillNames.filter((name)=>!present.includes(name));
+    return {
+        path: displayHome(root, rt.homeDir),
+        required: rt.builtInSkillNames.length,
+        present: present.length,
+        missing: [
+            ...missing
+        ],
+        status: "info",
+        errors: []
+    };
+}
+async function scriptCheck(installed, bundled, rt) {
+    let installedText;
+    try {
+        installedText = await rt.readFile(installed);
+    } catch  {
+        return {
+            path: displayHome(installed, rt.homeDir),
+            present: false,
+            readable: false,
+            matchesBundledAsset: false,
+            status: "fail",
+            errors: [
+                "hook script is unavailable"
+            ]
+        };
+    }
+    try {
+        const bundledText = await rt.readFile(bundled);
+        const matches = installedText === bundledText;
+        return {
+            path: displayHome(installed, rt.homeDir),
+            present: true,
+            readable: true,
+            matchesBundledAsset: matches,
+            status: matches ? "pass" : "fail",
+            errors: matches ? [] : [
+                "hook script differs from the bundled AI DevKit asset"
+            ]
+        };
+    } catch  {
+        return {
+            path: displayHome(installed, rt.homeDir),
+            present: true,
+            readable: true,
+            matchesBundledAsset: false,
+            status: "fail",
+            errors: [
+                "bundled hook asset is unavailable"
+            ]
+        };
+    }
+}
+function containsHook(root, event, command) {
+    const hooks = record(record(root)?.hooks);
+    const entries = hooks?.[event];
+    if (!Array.isArray(entries)) return false;
+    return entries.some((entry)=>{
+        const commands = record(entry)?.hooks;
+        return Array.isArray(commands) && commands.some((hook)=>{
+            const item = record(hook);
+            return item?.type === "command" && item.command === command;
+        });
+    });
+}
+async function registrationCheck(target, event, command, rt) {
+    try {
+        const parsed = JSON.parse(await rt.readFile(target));
+        const valid = containsHook(parsed, event, command);
+        return {
+            path: displayHome(target, rt.homeDir),
+            event,
+            command,
+            present: true,
+            valid,
+            status: valid ? "pass" : "fail",
+            errors: valid ? [] : [
+                "required hook registration is missing"
+            ]
+        };
+    } catch  {
+        return {
+            path: displayHome(target, rt.homeDir),
+            event,
+            command,
+            present: false,
+            valid: false,
+            status: "fail",
+            errors: [
+                "hook configuration is missing or invalid"
+            ]
+        };
+    }
+}
+async function mappingCheck(target, rt) {
+    let text;
+    try {
+        text = await rt.readFile(target);
+    } catch  {
+        return {
+            path: displayHome(target, rt.homeDir),
+            present: false,
+            valid: false,
+            invalidEntries: 0,
+            staleEntries: 0,
+            status: "warn",
+            errors: [
+                "session mapping has not been created"
+            ]
+        };
+    }
+    let parsed = null;
+    try {
+        parsed = record(JSON.parse(text));
+    } catch  {
+    // Fixed safe error below.
+    }
+    if (!parsed) {
+        return {
+            path: displayHome(target, rt.homeDir),
+            present: true,
+            valid: false,
+            invalidEntries: 0,
+            staleEntries: 0,
+            status: "fail",
+            errors: [
+                "session mapping is invalid"
+            ]
+        };
+    }
+    const entries = await Promise.all(Object.entries(parsed).map(async ([pid, sessionPath])=>{
+        if (!/^\d+$/.test(pid) || typeof sessionPath !== "string" || !sessionPath) {
+            return {
+                valid: false,
+                stale: false
+            };
+        }
+        return {
+            valid: true,
+            stale: !await accessible(sessionPath, rt)
+        };
+    }));
+    const invalidEntries = entries.filter((entry)=>!entry.valid).length;
+    const staleEntries = entries.filter((entry)=>entry.stale).length;
+    const valid = invalidEntries === 0;
+    return {
+        path: displayHome(target, rt.homeDir),
+        present: true,
+        valid,
+        invalidEntries,
+        staleEntries,
+        status: !valid ? "fail" : staleEntries ? "warn" : "pass",
+        errors: !valid ? [
+            "session mapping contains invalid entries"
+        ] : staleEntries ? [
+            "session mapping contains stale entries"
+        ] : []
+    };
+}
+async function codexAuthCheck(rt) {
+    try {
+        const value = await rt.codexAuth();
+        return {
+            state: value === true ? "authenticated" : value === false ? "unauthenticated" : "unknown",
+            source: displayHome(join(rt.homeDir, ".codex", "auth.json"), rt.homeDir),
+            provider: null,
+            availableProviders: [],
+            status: value === true ? "pass" : value === false ? "fail" : "warn",
+            errors: value === true ? [] : [
+                value === false ? "Codex is not authenticated" : "Codex authentication is unknown"
+            ]
+        };
+    } catch  {
+        return {
+            state: "unknown",
+            source: "~/.codex/auth.json",
+            provider: null,
+            availableProviders: [],
+            status: "warn",
+            errors: [
+                "Codex authentication probe failed"
+            ]
+        };
+    }
+}
+async function claudeAuthCheck(rt) {
+    try {
+        const result = await rt.runCommand("claude", [
+            "auth",
+            "status",
+            "--json"
+        ]);
+        const parsed = record(JSON.parse(result.stdout));
+        const authenticated = parsed?.loggedIn === true || parsed?.authenticated === true;
+        const unauthenticated = parsed?.loggedIn === false || parsed?.authenticated === false;
+        return {
+            state: authenticated ? "authenticated" : unauthenticated ? "unauthenticated" : "unknown",
+            source: "claude auth status --json",
+            provider: null,
+            availableProviders: [],
+            status: authenticated ? "pass" : unauthenticated ? "fail" : "warn",
+            errors: authenticated ? [] : [
+                unauthenticated ? "Claude is not authenticated" : "Claude authentication is unknown"
+            ]
+        };
+    } catch  {
+        return {
+            state: "unknown",
+            source: "claude auth status --json",
+            provider: null,
+            availableProviders: [],
+            status: "warn",
+            errors: [
+                "Claude authentication probe failed"
+            ]
+        };
+    }
+}
+function piProviderNames(parsed) {
+    const names = new Set();
+    if (nonEmpty(parsed.provider)) names.add(parsed.provider.trim());
+    const providers = record(parsed.providers);
+    if (providers) {
+        for (const name of Object.keys(providers)){
+            if (name.trim()) names.add(name);
+        }
+    }
+    for (const [name, value] of Object.entries(parsed)){
+        if (name === "provider" || name === "providers") continue;
+        if (record(value) && name.trim()) names.add(name);
+    }
+    return [
+        ...names
+    ].sort();
+}
+async function piAuthCheck(rt) {
+    const sourcePath = join(rt.homeDir, ".pi", "agent", "auth.json");
+    try {
+        const parsed = record(JSON.parse(await rt.readFile(sourcePath)));
+        if (!parsed) throw new Error("invalid");
+        const availableProviders = piProviderNames(parsed);
+        const provider = nonEmpty(parsed.provider) ? parsed.provider.trim() : null;
+        const authenticated = availableProviders.length > 0;
+        return {
+            state: authenticated ? "authenticated" : "unauthenticated",
+            source: displayHome(sourcePath, rt.homeDir),
+            provider,
+            availableProviders,
+            status: authenticated ? "pass" : "fail",
+            errors: authenticated ? [] : [
+                "Pi credential file has no configured model provider"
+            ]
+        };
+    } catch  {
+        return {
+            state: "unauthenticated",
+            source: displayHome(sourcePath, rt.homeDir),
+            provider: null,
+            availableProviders: [],
+            status: "fail",
+            errors: [
+                "Pi credential file is missing or invalid"
+            ]
+        };
+    }
+}
+async function opencodeAuthCheck(rt) {
+    try {
+        const result = await rt.runCommand("opencode", [
+            "auth",
+            "list"
+        ]);
+        const availableProviders = opencodeAuthProviderNames(result.stdout);
+        const authenticated = availableProviders.length > 0;
+        return {
+            state: authenticated ? "authenticated" : "unauthenticated",
+            source: "opencode auth list",
+            provider: null,
+            availableProviders,
+            status: authenticated ? "pass" : "fail",
+            errors: authenticated ? [] : [
+                "OpenCode has no configured credentials"
+            ]
+        };
+    } catch  {
+        return {
+            state: "unknown",
+            source: "opencode auth list",
+            provider: null,
+            availableProviders: [],
+            status: "warn",
+            errors: [
+                "OpenCode authentication probe failed"
+            ]
+        };
+    }
+}
+async function copilotAuthCheck(rt) {
+    try {
+        await rt.runCommand("gh", [
+            "auth",
+            "status",
+            "--hostname",
+            "github.com"
+        ]);
+        return {
+            state: "authenticated",
+            source: "gh auth status --hostname github.com",
+            provider: "github",
+            availableProviders: [
+                "GitHub"
+            ],
+            status: "pass",
+            errors: []
+        };
+    } catch  {
+        return {
+            state: "unknown",
+            source: "gh auth status --hostname github.com",
+            provider: null,
+            availableProviders: [
+                "GitHub"
+            ],
+            status: "warn",
+            errors: [
+                "Copilot authentication could not be verified through GitHub CLI"
+            ]
+        };
+    }
+}
+function opencodeAuthProviderNames(output) {
+    const names = new Set();
+    for (const line of stripAnsi(output).split(/\r?\n/)){
+        const match = /^\s*[●*+-]\s+(.+?)\s*$/.exec(line);
+        if (!match) continue;
+        const name = match[1].replace(/\s+(?:api|oauth|[\w-]*token|[A-Z][A-Z0-9_]+)$/i, "").trim();
+        if (name && !/^\d+\s+(?:credentials?|environment variables?)$/i.test(name)) names.add(name);
+    }
+    return [
+        ...names
+    ].sort();
+}
+function stripAnsi(value) {
+    return value.replace(ANSI_ESCAPE_PATTERN, "");
+}
+async function codexIntegrationCheck(rt) {
+    const script = await scriptCheck(join(rt.homeDir, ".codex", "hooks", "codex-session-mapping.cjs"), join(rt.assetRoot ?? "", "codex", "codex-session-mapping.cjs"), rt);
+    const registration = await registrationCheck(join(rt.homeDir, ".codex", "hooks.json"), "SessionStart", "node ~/.codex/hooks/codex-session-mapping.cjs", rt);
+    const mappingFile = await mappingCheck(join(rt.homeDir, ".codex", "ai-devkit", "sessions.json"), rt);
+    const installed = script.status === "pass" && registration.status === "pass";
+    return {
+        label: "ai-devkit hook",
+        installed,
+        status: worstReadinessStatus([
+            script.status,
+            registration.status,
+            mappingFile.status
+        ]),
+        errors: [
+            ...script.errors,
+            ...registration.errors,
+            ...mappingFile.errors
+        ],
+        details: {
+            sessionMappingScript: script,
+            registration,
+            mappingFile
+        }
+    };
+}
+async function claudeIntegrationCheck(rt) {
+    const script = await scriptCheck(join(rt.homeDir, ".claude", "hooks", "claude-prompt-hook.js"), join(rt.assetRoot ?? "", "claude", "claude-prompt-hook.js"), rt);
+    const registration = await registrationCheck(join(rt.homeDir, ".claude", "settings.json"), "PreToolUse", "node ~/.claude/hooks/claude-prompt-hook.js", rt);
+    const installed = script.status === "pass" && registration.status === "pass";
+    return {
+        label: "ai-devkit hook",
+        installed,
+        status: worstReadinessStatus([
+            script.status,
+            registration.status
+        ]),
+        errors: [
+            ...script.errors,
+            ...registration.errors
+        ],
+        details: {
+            promptScript: script,
+            registration
+        }
+    };
+}
+async function piIntegrationCheck(rt) {
+    let installed = false;
+    try {
+        const result = await rt.runCommand("pi", [
+            "list"
+        ]);
+        installed = isPiSessionTrackerListed(result.stdout);
+    } catch  {
+    // Safe fixed result below.
+    }
+    const mapping = await mappingCheck(join(rt.homeDir, ".pi", "agent", "sessions.json"), rt);
+    const mappingStatus = mapping.valid || !mapping.present ? "pass" : "fail";
+    const status = worstReadinessStatus([
+        installed ? "pass" : "fail",
+        mappingStatus
+    ]);
+    return {
+        label: "ai-devkit plugin",
+        installed,
+        status,
+        errors: [
+            ...!installed ? [
+                "Pi session tracker is not registered"
+            ] : [],
+            ...mappingStatus === "fail" ? mapping.errors : []
+        ],
+        details: {
+            package: "@ai-devkit/pi-session-tracker",
+            registryPath: mapping.path,
+            registryValid: mapping.valid,
+            invalidEntries: mapping.invalidEntries,
+            staleEntries: mapping.staleEntries
+        }
+    };
+}
+function isPiSessionTrackerListed(output) {
+    const normalized = output.toLowerCase();
+    return normalized.includes("@ai-devkit/pi-session-tracker") || /\bsession[\s-]+tracker\b/.test(normalized);
+}
+const AUTH_CHECKS = {
+    claude: claudeAuthCheck,
+    codex: codexAuthCheck,
+    copilot: copilotAuthCheck,
+    opencode: opencodeAuthCheck,
+    pi: piAuthCheck
+};
+const INTEGRATION_CHECKS = {
+    claude: claudeIntegrationCheck,
+    codex: codexIntegrationCheck,
+    pi: piIntegrationCheck
+};
+async function authCheck(agent, rt) {
+    return AUTH_CHECKS[agent]?.(rt);
+}
+async function integrationCheck(agent, rt) {
+    return INTEGRATION_CHECKS[agent]?.(rt);
+}
+export async function getAgentReadinessReport(agent, options = {}) {
+    return agentReadiness(agent, runtime(options));
+}
+async function agentReadiness(agent, rt) {
+    const [executable, globalConfig, builtInSkills, auth, integration] = await Promise.all([
+        executableCheck(agent, rt),
+        directoryCheck(agent, rt),
+        builtInSkillsCheck(agent, rt),
+        authCheck(agent, rt),
+        integrationCheck(agent, rt)
+    ]);
+    return {
+        type: agent,
+        executable,
+        globalConfig,
+        builtInSkills,
+        auth,
+        integration,
+        status: worstReadinessStatus([
+            executable.status,
+            globalConfig.status,
+            ...auth ? [
+                auth.status
+            ] : [],
+            ...integration ? [
+                integration.status
+            ] : []
+        ])
+    };
+}
+export async function getAgentReadinessReports(options = {}) {
+    const rt = runtime(options);
+    const entries = await Promise.all(READINESS_AGENT_TYPES.map(async (agent)=>[
+            agent,
+            await agentReadiness(agent, rt)
+        ]));
+    return Object.fromEntries(entries);
+}
+
+//# sourceMappingURL=AgentReadiness.js.map