@ai-devkit/agent-manager 0.30.0 → 0.32.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