@bhimudev/gnanai 0.4.0

package/dist/utils/merge-claude-settings.js

@@ -0,0 +1,133 @@
+import fs from 'fs-extra';
+import path from 'path';
+/**
+ * Read .claude/settings.json from a project root.
+ * Returns an empty object if the file does not exist or is malformed.
+ */
+export async function readClaudeSettings(projectRoot) {
+    const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+    try {
+        const content = await fs.readFile(settingsPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Atomically write .claude/settings.json for a project root.
+ * Uses temp file + rename to prevent corruption.
+ */
+export async function writeClaudeSettings(projectRoot, settings) {
+    const settingsDir = path.join(projectRoot, '.claude');
+    const settingsPath = path.join(settingsDir, 'settings.json');
+    const tmpPath = path.join(settingsDir, `.settings.json.tmp.${Date.now()}`);
+    await fs.ensureDir(settingsDir);
+    await fs.writeFile(tmpPath, JSON.stringify(settings, null, 2) + '\n');
+    await fs.rename(tmpPath, settingsPath);
+}
+/**
+ * Read .claude/settings.local.json from a project root.
+ * Returns an empty object if the file does not exist or is malformed.
+ */
+export async function readSettingsLocal(projectRoot) {
+    const localPath = path.join(projectRoot, '.claude', 'settings.local.json');
+    try {
+        const content = await fs.readFile(localPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Atomically write .claude/settings.local.json for a project root.
+ */
+async function writeSettingsLocal(projectRoot, data) {
+    const settingsDir = path.join(projectRoot, '.claude');
+    const localPath = path.join(settingsDir, 'settings.local.json');
+    const tmpPath = path.join(settingsDir, `.settings.local.json.tmp.${Date.now()}`);
+    await fs.ensureDir(settingsDir);
+    await fs.writeFile(tmpPath, JSON.stringify(data, null, 2) + '\n');
+    await fs.rename(tmpPath, localPath);
+}
+/**
+ * Add a permission rule to the allow list in .claude/settings.local.json.
+ * Idempotent — skips if the rule already exists.
+ */
+export async function addAllowPermission(projectRoot, rule) {
+    const settings = await readSettingsLocal(projectRoot);
+    if (!settings.permissions) {
+        settings.permissions = {};
+    }
+    if (!settings.permissions.allow) {
+        settings.permissions.allow = [];
+    }
+    if (!settings.permissions.allow.includes(rule)) {
+        settings.permissions.allow.push(rule);
+        await writeSettingsLocal(projectRoot, settings);
+    }
+}
+/**
+ * Remove a permission rule from the allow list in .claude/settings.local.json.
+ * No-op if the rule does not exist.
+ */
+export async function removeAllowPermission(projectRoot, rule) {
+    const settings = await readSettingsLocal(projectRoot);
+    if (!settings.permissions?.allow)
+        return;
+    const idx = settings.permissions.allow.indexOf(rule);
+    if (idx >= 0) {
+        settings.permissions.allow.splice(idx, 1);
+        await writeSettingsLocal(projectRoot, settings);
+    }
+}
+/**
+ * Read .mcp.json from a project root.
+ * Claude Code reads project-level MCP servers from this file (not .claude/settings.json).
+ * Returns an empty object if the file does not exist or is malformed.
+ */
+export async function readMcpJson(projectRoot) {
+    const mcpJsonPath = path.join(projectRoot, '.mcp.json');
+    try {
+        const content = await fs.readFile(mcpJsonPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Atomically write .mcp.json for a project root.
+ */
+async function writeMcpJson(projectRoot, data) {
+    const mcpJsonPath = path.join(projectRoot, '.mcp.json');
+    const tmpPath = path.join(projectRoot, `.mcp.json.tmp.${Date.now()}`);
+    await fs.writeFile(tmpPath, JSON.stringify(data, null, 2) + '\n');
+    await fs.rename(tmpPath, mcpJsonPath);
+}
+/**
+ * Add an MCP server entry to .mcp.json (project root).
+ * Claude Code reads project-level MCP servers from .mcp.json.
+ * Preserves existing entries.
+ */
+export async function addMcpServer(projectRoot, serverName, config) {
+    const mcpJson = await readMcpJson(projectRoot);
+    if (!mcpJson.mcpServers) {
+        mcpJson.mcpServers = {};
+    }
+    mcpJson.mcpServers[serverName] = config;
+    await writeMcpJson(projectRoot, mcpJson);
+}
+/**
+ * Remove an MCP server entry from .mcp.json (project root).
+ * No-op if the server does not exist.
+ */
+export async function removeMcpServer(projectRoot, serverName) {
+    const mcpJson = await readMcpJson(projectRoot);
+    if (mcpJson.mcpServers && serverName in mcpJson.mcpServers) {
+        delete mcpJson.mcpServers[serverName];
+        await writeMcpJson(projectRoot, mcpJson);
+    }
+}
+//# sourceMappingURL=merge-claude-settings.js.map

package/dist/utils/merge-claude-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-claude-settings.js","sourceRoot":"","sources":["../../src/utils/merge-claude-settings.ts"],"names":[],"mappings":"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"}

package/dist/utils/migration.d.ts

@@ -0,0 +1,74 @@
+import { type VersionFile } from './version-tracker.js';
+/**
+ * Result of a migration operation.
+ */
+export interface MigrationResult {
+    success: boolean;
+    migrated: boolean;
+    versionFile: VersionFile | null;
+    warnings: string[];
+    error?: string;
+}
+/**
+ * Information about a template file.
+ */
+export interface TemplateFile {
+    relativePath: string;
+    templatePath: string;
+    hash: string | null;
+}
+/**
+ * Get the templates directory path.
+ */
+export declare function getTemplatesDir(): string;
+/**
+ * Get the core agents templates directory path.
+ */
+export declare function getCoreAgentsTemplatesDir(): string;
+/**
+ * Check if an installation is legacy (pre-version.json).
+ */
+export declare function detectLegacyInstall(claudeDir: string): Promise<boolean>;
+/**
+ * Check if a .claude directory exists.
+ */
+export declare function hasExistingInstall(claudeDir: string): Promise<boolean>;
+/**
+ * Get hashes of all current archai template files.
+ * Returns a map of relative paths (as they would be installed) to their hashes.
+ */
+export declare function getTemplateHashes(): Promise<Map<string, string>>;
+/**
+ * Get list of all template files with their paths and hashes.
+ */
+export declare function getTemplateFiles(): Promise<TemplateFile[]>;
+/**
+ * Get the path to a specific template file.
+ */
+export declare function getTemplatePath(relativePath: string): string | null;
+/**
+ * Migrate a legacy installation to use version.json.
+ *
+ * This function:
+ * 1. Gets current template hashes
+ * 2. Compares each existing file to templates
+ * 3. If file matches template exactly, use template hash as base
+ * 4. If file differs, use current file hash as base (assume user modified)
+ * 5. Marks specialist files as generated
+ * 6. Creates version.json
+ */
+export declare function migrateFromLegacy(claudeDir: string, archaiVersion: string): Promise<MigrationResult>;
+/**
+ * Check if migration is needed and perform it if necessary.
+ * Safe to call on any installation - will do nothing if not needed.
+ */
+export declare function ensureMigrated(claudeDir: string, archaiVersion: string): Promise<MigrationResult>;
+/**
+ * Get the archai version from package.json.
+ */
+export declare function getArchaiVersion(): Promise<string>;
+/**
+ * List files that exist locally but not in templates (custom files).
+ */
+export declare function getCustomFiles(claudeDir: string): Promise<string[]>;
+//# sourceMappingURL=migration.d.ts.map

package/dist/utils/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../src/utils/migration.ts"],"names":[],"mappings":"AAKA,OAAO,EAML,KAAK,WAAW,EAEjB,MAAM,sBAAsB,CAAC;AAK9B;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM7E;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE5E;AAgCD;;;GAGG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAoCtE;AAED;;GAEG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAuChE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoBnE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,eAAe,CAAC,CAkI1B;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,eAAe,CAAC,CAgB1B;AAED;;GAEG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CASxD;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA6BzE"}

package/dist/utils/migration.js

@@ -0,0 +1,345 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { logger } from './logger.js';
+import { hashFile, isGeneratedSpecialist } from './file-comparison.js';
+import { loadVersionFile, saveVersionFile, createVersionFile, versionFileExists, normalizePath, } from './version-tracker.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Get the templates directory path.
+ */
+export function getTemplatesDir() {
+    return path.resolve(__dirname, '../../templates');
+}
+/**
+ * Get the core agents templates directory path.
+ */
+export function getCoreAgentsTemplatesDir() {
+    return path.join(getTemplatesDir(), 'core-agents');
+}
+/**
+ * Check if an installation is legacy (pre-version.json).
+ */
+export async function detectLegacyInstall(claudeDir) {
+    // A legacy install has a .claude directory but no version.json
+    const claudeExists = await fs.pathExists(claudeDir);
+    const hasVersionFile = await versionFileExists(claudeDir);
+    return claudeExists && !hasVersionFile;
+}
+/**
+ * Check if a .claude directory exists.
+ */
+export async function hasExistingInstall(claudeDir) {
+    return fs.pathExists(claudeDir);
+}
+/**
+ * Get all files recursively from a directory.
+ */
+async function getFilesRecursive(dir, base = dir) {
+    const files = [];
+    if (!await fs.pathExists(dir)) {
+        return files;
+    }
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            // Skip certain directories
+            if (entry.name === 'backups' || entry.name === 'node_modules') {
+                continue;
+            }
+            const subFiles = await getFilesRecursive(fullPath, base);
+            files.push(...subFiles);
+        }
+        else if (entry.isFile()) {
+            files.push(path.relative(base, fullPath));
+        }
+    }
+    return files;
+}
+/**
+ * Get hashes of all current archai template files.
+ * Returns a map of relative paths (as they would be installed) to their hashes.
+ */
+export async function getTemplateHashes() {
+    const hashes = new Map();
+    const templatesDir = getTemplatesDir();
+    const coreAgentsDir = getCoreAgentsTemplatesDir();
+    // Core agents templates → .claude/agents/
+    if (await fs.pathExists(coreAgentsDir)) {
+        const agentFiles = await getFilesRecursive(coreAgentsDir);
+        for (const file of agentFiles) {
+            const templatePath = path.join(coreAgentsDir, file);
+            const hash = await hashFile(templatePath);
+            if (hash) {
+                // These get installed to .claude/agents/
+                const installedPath = normalizePath(`.claude/agents/${file}`);
+                hashes.set(installedPath, hash);
+            }
+        }
+    }
+    // Root templates (PROMPTS.md, etc.) → .claude/
+    const rootTemplates = ['PROMPTS.md', 'ARCHAI_README.md'];
+    for (const file of rootTemplates) {
+        const templatePath = path.join(templatesDir, file);
+        if (await fs.pathExists(templatePath)) {
+            const hash = await hashFile(templatePath);
+            if (hash) {
+                // Map to their installed locations
+                const installedPath = file === 'ARCHAI_README.md'
+                    ? normalizePath('.claude/ARCHAI_README.md')
+                    : normalizePath(`.claude/${file}`);
+                hashes.set(installedPath, hash);
+            }
+        }
+    }
+    return hashes;
+}
+/**
+ * Get list of all template files with their paths and hashes.
+ */
+export async function getTemplateFiles() {
+    const files = [];
+    const templatesDir = getTemplatesDir();
+    const coreAgentsDir = getCoreAgentsTemplatesDir();
+    // Core agents
+    if (await fs.pathExists(coreAgentsDir)) {
+        const agentFiles = await getFilesRecursive(coreAgentsDir);
+        for (const file of agentFiles) {
+            const templatePath = path.join(coreAgentsDir, file);
+            const hash = await hashFile(templatePath);
+            files.push({
+                relativePath: normalizePath(`.claude/agents/${file}`),
+                templatePath,
+                hash,
+            });
+        }
+    }
+    // Root templates
+    const rootTemplates = [
+        { src: 'PROMPTS.md', dest: '.claude/PROMPTS.md' },
+        { src: 'ARCHAI_README.md', dest: '.claude/ARCHAI_README.md' },
+        { src: 'CLAUDE.md', dest: 'CLAUDE.md' },
+    ];
+    for (const { src, dest } of rootTemplates) {
+        const templatePath = path.join(templatesDir, src);
+        if (await fs.pathExists(templatePath)) {
+            const hash = await hashFile(templatePath);
+            files.push({
+                relativePath: normalizePath(dest),
+                templatePath,
+                hash,
+            });
+        }
+    }
+    return files;
+}
+/**
+ * Get the path to a specific template file.
+ */
+export function getTemplatePath(relativePath) {
+    const normalized = normalizePath(relativePath);
+    const templatesDir = getTemplatesDir();
+    // Check if it's a core agent
+    if (normalized.startsWith('.claude/agents/')) {
+        const agentFile = normalized.replace('.claude/agents/', '');
+        const templatePath = path.join(getCoreAgentsTemplatesDir(), agentFile);
+        return templatePath;
+    }
+    // Check other template mappings
+    if (normalized === '.claude/PROMPTS.md') {
+        return path.join(templatesDir, 'PROMPTS.md');
+    }
+    if (normalized === '.claude/ARCHAI_README.md') {
+        return path.join(templatesDir, 'ARCHAI_README.md');
+    }
+    return null;
+}
+/**
+ * Migrate a legacy installation to use version.json.
+ *
+ * This function:
+ * 1. Gets current template hashes
+ * 2. Compares each existing file to templates
+ * 3. If file matches template exactly, use template hash as base
+ * 4. If file differs, use current file hash as base (assume user modified)
+ * 5. Marks specialist files as generated
+ * 6. Creates version.json
+ */
+export async function migrateFromLegacy(claudeDir, archaiVersion) {
+    const warnings = [];
+    try {
+        // Check if already migrated
+        if (await versionFileExists(claudeDir)) {
+            return {
+                success: true,
+                migrated: false,
+                versionFile: await loadVersionFile(claudeDir),
+                warnings: ['Already migrated (version.json exists)'],
+            };
+        }
+        // Check if .claude directory exists
+        if (!await fs.pathExists(claudeDir)) {
+            return {
+                success: false,
+                migrated: false,
+                versionFile: null,
+                warnings: [],
+                error: '.claude directory does not exist',
+            };
+        }
+        // Get template hashes
+        const templateHashes = await getTemplateHashes();
+        // Get all files in the .claude directory
+        const existingFiles = await getFilesRecursive(claudeDir);
+        const files = {};
+        const expectedFiles = [];
+        // Process each existing file — only track template files and generated specialists.
+        // Non-template files (settings.local.json, status/*, plans/*, etc.) are user-owned
+        // and must NOT be tracked, otherwise they'd be flagged as orphaned/deprecated.
+        for (const relativePath of existingFiles) {
+            const fullPath = path.join(claudeDir, relativePath);
+            const normalizedPath = normalizePath(`.claude/${relativePath}`);
+            // Skip version.json itself if it somehow exists
+            if (relativePath === 'version.json') {
+                continue;
+            }
+            // Check if this is a generated specialist
+            const isGenerated = isGeneratedSpecialist(normalizedPath);
+            if (isGenerated) {
+                // Generated files have no base hash
+                files[normalizedPath] = {
+                    baseHash: null,
+                    isGenerated: true,
+                };
+                logger.debug(`Marked as generated: ${normalizedPath}`);
+                continue;
+            }
+            // Only track files that match a known template path
+            const templateHash = templateHashes.get(normalizedPath);
+            if (!templateHash) {
+                logger.debug(`Skipping non-template file: ${normalizedPath}`);
+                continue;
+            }
+            // Get current file hash
+            const currentHash = await hashFile(fullPath);
+            if (currentHash === templateHash) {
+                // File matches template exactly - not user modified
+                files[normalizedPath] = {
+                    baseHash: templateHash,
+                    isGenerated: false,
+                };
+                expectedFiles.push(normalizedPath);
+                logger.debug(`Unchanged from template: ${normalizedPath}`);
+            }
+            else if (currentHash) {
+                // File differs from template - user modified or old archai version.
+                // Set baseHash to null so determineFileStatus returns 'modified_by_user',
+                // which prompts the user instead of silently overwriting their changes.
+                files[normalizedPath] = {
+                    baseHash: null,
+                    isGenerated: false,
+                };
+                warnings.push(`${normalizedPath} differs from template, assuming user-modified`);
+                expectedFiles.push(normalizedPath);
+                logger.debug(`User modified template file: ${normalizedPath}`);
+            }
+        }
+        // Add expected files from templates that don't exist locally
+        for (const [templatePath, _] of templateHashes) {
+            if (!files[templatePath] && !expectedFiles.includes(templatePath)) {
+                expectedFiles.push(templatePath);
+            }
+        }
+        // Create version file
+        const versionFile = createVersionFile(archaiVersion, files, expectedFiles);
+        // Save it
+        const saved = await saveVersionFile(claudeDir, versionFile);
+        if (!saved) {
+            return {
+                success: false,
+                migrated: false,
+                versionFile: null,
+                warnings,
+                error: 'Failed to save version.json',
+            };
+        }
+        logger.debug(`Migration complete: ${Object.keys(files).length} files tracked`);
+        return {
+            success: true,
+            migrated: true,
+            versionFile,
+            warnings,
+        };
+    }
+    catch (error) {
+        logger.debug('Migration failed', error);
+        return {
+            success: false,
+            migrated: false,
+            versionFile: null,
+            warnings,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Check if migration is needed and perform it if necessary.
+ * Safe to call on any installation - will do nothing if not needed.
+ */
+export async function ensureMigrated(claudeDir, archaiVersion) {
+    const isLegacy = await detectLegacyInstall(claudeDir);
+    if (!isLegacy) {
+        // Not a legacy install - either fresh or already migrated
+        const versionFile = await loadVersionFile(claudeDir);
+        return {
+            success: true,
+            migrated: false,
+            versionFile,
+            warnings: [],
+        };
+    }
+    // Perform migration
+    return migrateFromLegacy(claudeDir, archaiVersion);
+}
+/**
+ * Get the archai version from package.json.
+ */
+export async function getArchaiVersion() {
+    const pkgPath = path.resolve(__dirname, '../../package.json');
+    try {
+        const pkg = await fs.readJson(pkgPath);
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * List files that exist locally but not in templates (custom files).
+ */
+export async function getCustomFiles(claudeDir) {
+    const templateHashes = await getTemplateHashes();
+    const templatePaths = new Set(templateHashes.keys());
+    const existingFiles = await getFilesRecursive(claudeDir);
+    const customFiles = [];
+    for (const relativePath of existingFiles) {
+        const normalizedPath = normalizePath(`.claude/${relativePath}`);
+        // Skip version.json
+        if (relativePath === 'version.json') {
+            continue;
+        }
+        // Skip if it's a known template
+        if (templatePaths.has(normalizedPath)) {
+            continue;
+        }
+        // Skip generated specialists
+        if (isGeneratedSpecialist(normalizedPath)) {
+            continue;
+        }
+        customFiles.push(normalizedPath);
+    }
+    return customFiles;
+}
+//# sourceMappingURL=migration.js.map

package/dist/utils/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.js","sourceRoot":"","sources":["../../src/utils/migration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,UAAU,CAAC;AAC1B,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAe,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EACL,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,GAGd,MAAM,sBAAsB,CAAC;AAE9B,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAsB3C;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB;IACvC,OAAO,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,aAAa,CAAC,CAAC;AACrD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,SAAiB;IACzD,+DAA+D;IAC/D,MAAM,YAAY,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACpD,MAAM,cAAc,GAAG,MAAM,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAE1D,OAAO,YAAY,IAAI,CAAC,cAAc,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,SAAiB;IACxD,OAAO,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,iBAAiB,CAAC,GAAW,EAAE,OAAe,GAAG;IAC9D,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,IAAI,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAE5C,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,2BAA2B;YAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;gBAC9D,SAAS;YACX,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACzD,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;QAC1B,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;IACvC,MAAM,aAAa,GAAG,yBAAyB,EAAE,CAAC;IAElD,0CAA0C;IAC1C,IAAI,MAAM,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QACvC,MAAM,UAAU,GAAG,MAAM,iBAAiB,CAAC,aAAa,CAAC,CAAC;QAC1D,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;YACpD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC;YAC1C,IAAI,IAAI,EAAE,CAAC;gBACT,yCAAyC;gBACzC,MAAM,aAAa,GAAG,aAAa,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC;gBAC9D,MAAM,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;IACH,CAAC;IAED,+CAA+C;IAC/C,MAAM,aAAa,GAAG,CAAC,YAAY,EAAE,kBAAkB,CAAC,CAAC;IACzD,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QACnD,IAAI,MAAM,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC;YAC1C,IAAI,IAAI,EAAE,CAAC;gBACT,mCAAmC;gBACnC,MAAM,aAAa,GAAG,IAAI,KAAK,kBAAkB;oBAC/C,CAAC,CAAC,aAAa,CAAC,0BAA0B,CAAC;oBAC3C,CAAC,CAAC,aAAa,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;gBACrC,MAAM,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;IACvC,MAAM,aAAa,GAAG,yBAAyB,EAAE,CAAC;IAElD,cAAc;IACd,IAAI,MAAM,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QACvC,MAAM,UAAU,GAAG,MAAM,iBAAiB,CAAC,aAAa,CAAC,CAAC;QAC1D,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;YACpD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC;YAC1C,KAAK,CAAC,IAAI,CAAC;gBACT,YAAY,EAAE,aAAa,CAAC,kBAAkB,IAAI,EAAE,CAAC;gBACrD,YAAY;gBACZ,IAAI;aACL,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,iBAAiB;IACjB,MAAM,aAAa,GAAG;QACpB,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,oBAAoB,EAAE;QACjD,EAAE,GAAG,EAAE,kBAAkB,EAAE,IAAI,EAAE,0BAA0B,EAAE;QAC7D,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE;KACxC,CAAC;IAEF,KAAK,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,aAAa,EAAE,CAAC;QAC1C,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;QAClD,IAAI,MAAM,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC;YAC1C,KAAK,CAAC,IAAI,CAAC;gBACT,YAAY,EAAE,aAAa,CAAC,IAAI,CAAC;gBACjC,YAAY;gBACZ,IAAI;aACL,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,YAAoB;IAClD,MAAM,UAAU,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;IAEvC,6BAA6B;IAC7B,IAAI,UAAU,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAC7C,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;QAC5D,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,SAAS,CAAC,CAAC;QACvE,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,gCAAgC;IAChC,IAAI,UAAU,KAAK,oBAAoB,EAAE,CAAC;QACxC,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,UAAU,KAAK,0BAA0B,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,kBAAkB,CAAC,CAAC;IACrD,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAiB,EACjB,aAAqB;IAErB,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,CAAC;QACH,4BAA4B;QAC5B,IAAI,MAAM,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;YACvC,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,MAAM,eAAe,CAAC,SAAS,CAAC;gBAC7C,QAAQ,EAAE,CAAC,wCAAwC,CAAC;aACrD,CAAC;QACJ,CAAC;QAED,oCAAoC;QACpC,IAAI,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACpC,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,IAAI;gBACjB,QAAQ,EAAE,EAAE;gBACZ,KAAK,EAAE,kCAAkC;aAC1C,CAAC;QACJ,CAAC;QAED,sBAAsB;QACtB,MAAM,cAAc,GAAG,MAAM,iBAAiB,EAAE,CAAC;QAEjD,yCAAyC;QACzC,MAAM,aAAa,GAAG,MAAM,iBAAiB,CAAC,SAAS,CAAC,CAAC;QACzD,MAAM,KAAK,GAA+B,EAAE,CAAC;QAC7C,MAAM,aAAa,GAAa,EAAE,CAAC;QAEnC,oFAAoF;QACpF,mFAAmF;QACnF,+EAA+E;QAC/E,KAAK,MAAM,YAAY,IAAI,aAAa,EAAE,CAAC;YACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;YACpD,MAAM,cAAc,GAAG,aAAa,CAAC,WAAW,YAAY,EAAE,CAAC,CAAC;YAEhE,gDAAgD;YAChD,IAAI,YAAY,KAAK,cAAc,EAAE,CAAC;gBACpC,SAAS;YACX,CAAC;YAED,0CAA0C;YAC1C,MAAM,WAAW,GAAG,qBAAqB,CAAC,cAAc,CAAC,CAAC;YAE1D,IAAI,WAAW,EAAE,CAAC;gBAChB,oCAAoC;gBACpC,KAAK,CAAC,cAAc,CAAC,GAAG;oBACtB,QAAQ,EAAE,IAAI;oBACd,WAAW,EAAE,IAAI;iBAClB,CAAC;gBACF,MAAM,CAAC,KAAK,CAAC,wBAAwB,cAAc,EAAE,CAAC,CAAC;gBACvD,SAAS;YACX,CAAC;YAED,oDAAoD;YACpD,MAAM,YAAY,GAAG,cAAc,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;YACxD,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,MAAM,CAAC,KAAK,CAAC,+BAA+B,cAAc,EAAE,CAAC,CAAC;gBAC9D,SAAS;YACX,CAAC;YAED,wBAAwB;YACxB,MAAM,WAAW,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAE7C,IAAI,WAAW,KAAK,YAAY,EAAE,CAAC;gBACjC,oDAAoD;gBACpD,KAAK,CAAC,cAAc,CAAC,GAAG;oBACtB,QAAQ,EAAE,YAAY;oBACtB,WAAW,EAAE,KAAK;iBACnB,CAAC;gBACF,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;gBACnC,MAAM,CAAC,KAAK,CAAC,4BAA4B,cAAc,EAAE,CAAC,CAAC;YAC7D,CAAC;iBAAM,IAAI,WAAW,EAAE,CAAC;gBACvB,oEAAoE;gBACpE,0EAA0E;gBAC1E,wEAAwE;gBACxE,KAAK,CAAC,cAAc,CAAC,GAAG;oBACtB,QAAQ,EAAE,IAAI;oBACd,WAAW,EAAE,KAAK;iBACnB,CAAC;gBACF,QAAQ,CAAC,IAAI,CAAC,GAAG,cAAc,gDAAgD,CAAC,CAAC;gBACjF,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;gBACnC,MAAM,CAAC,KAAK,CAAC,gCAAgC,cAAc,EAAE,CAAC,CAAC;YACjE,CAAC;QACH,CAAC;QAED,6DAA6D;QAC7D,KAAK,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,IAAI,cAAc,EAAE,CAAC;YAC/C,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;gBAClE,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QAED,sBAAsB;QACtB,MAAM,WAAW,GAAG,iBAAiB,CAAC,aAAa,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC;QAE3E,UAAU;QACV,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QAC5D,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,IAAI;gBACjB,QAAQ;gBACR,KAAK,EAAE,6BAA6B;aACrC,CAAC;QACJ,CAAC;QAED,MAAM,CAAC,KAAK,CAAC,uBAAuB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,gBAAgB,CAAC,CAAC;QAE/E,OAAO;YACL,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,IAAI;YACd,WAAW;YACX,QAAQ;SACT,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;QACxC,OAAO;YACL,OAAO,EAAE,KAAK;YACd,QAAQ,EAAE,KAAK;YACf,WAAW,EAAE,IAAI;YACjB,QAAQ;YACR,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,SAAiB,EACjB,aAAqB;IAErB,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAEtD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,0DAA0D;QAC1D,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC;QACrD,OAAO;YACL,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,KAAK;YACf,WAAW;YACX,QAAQ,EAAE,EAAE;SACb,CAAC;IACJ,CAAC;IAED,oBAAoB;IACpB,OAAO,iBAAiB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;AACrD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC;IAE9D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACvC,OAAO,GAAG,CAAC,OAAO,IAAI,SAAS,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,SAAiB;IACpD,MAAM,cAAc,GAAG,MAAM,iBAAiB,EAAE,CAAC;IACjD,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC;IAErD,MAAM,aAAa,GAAG,MAAM,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACzD,MAAM,WAAW,GAAa,EAAE,CAAC;IAEjC,KAAK,MAAM,YAAY,IAAI,aAAa,EAAE,CAAC;QACzC,MAAM,cAAc,GAAG,aAAa,CAAC,WAAW,YAAY,EAAE,CAAC,CAAC;QAEhE,oBAAoB;QACpB,IAAI,YAAY,KAAK,cAAc,EAAE,CAAC;YACpC,SAAS;QACX,CAAC;QAED,gCAAgC;QAChC,IAAI,aAAa,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;YACtC,SAAS;QACX,CAAC;QAED,6BAA6B;QAC7B,IAAI,qBAAqB,CAAC,cAAc,CAAC,EAAE,CAAC;YAC1C,SAAS;QACX,CAAC;QAED,WAAW,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/utils/process-health.d.ts

@@ -0,0 +1,51 @@
+/**
+ * On-demand health assessment for tracked processes.
+ *
+ * Pure classification logic (`classifyHealth`) plus I/O wrappers
+ * (`assessHealth`, `assessAll`) that resolve process data from
+ * in-process registry or cross-process state files.
+ *
+ * @module process-health
+ * @since Task-PROC-004
+ */
+import type { ProcessHealthReport, ProcessHealthOptions } from '../types/index.js';
+/**
+ * Input shape for the pure classification function.
+ * Matches the subset of ProcessStateData needed for health assessment.
+ */
+interface ClassifyInput {
+    id: string;
+    pid: number;
+    state: string;
+    lastEventTime: number | null;
+    startTime: number;
+    eventCount: number;
+}
+/**
+ * Pure classification function — no I/O, no side effects.
+ * Exported for direct unit testing.
+ *
+ * Priority order: dead > zombie > stuck > idle > healthy.
+ */
+export declare function classifyHealth(data: ClassifyInput, alive: boolean, thresholds: {
+    idleThresholdMs: number;
+    stuckThresholdMs: number;
+}): ProcessHealthReport;
+/**
+ * Assess the health of a single tracked process.
+ *
+ * Checks the in-process registry first (freshest data), then falls back
+ * to cross-process state files on disk.
+ *
+ * @returns ProcessHealthReport or null if process not found
+ */
+export declare function assessHealth(id: string, opts?: ProcessHealthOptions): ProcessHealthReport | null;
+/**
+ * Assess the health of all tracked processes.
+ *
+ * Combines in-process registry entries with cross-process state files,
+ * deduplicating by ID (in-process wins).
+ */
+export declare function assessAll(opts?: ProcessHealthOptions): ProcessHealthReport[];
+export {};
+//# sourceMappingURL=process-health.d.ts.map

package/dist/utils/process-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-health.d.ts","sourceRoot":"","sources":["../../src/utils/process-health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,mBAAmB,EAAuB,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAIxG;;;GAGG;AACH,UAAU,aAAa;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,OAAO,EACd,UAAU,EAAE;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,GAChE,mBAAmB,CAyCrB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,mBAAmB,GAAG,IAAI,CA6BhG;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG,mBAAmB,EAAE,CAkC5E"}