@defai.digital/ax-cli 2.3.0 → 2.4.0

package/dist/utils/llm-optimized-instruction-generator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * LLM-Optimized Instruction Generator
+ * Generates token-efficient, comprehension-optimized project instructions
+ */
+import type { ProjectInfo } from '../types/project-analysis.js';
+interface OptimizationConfig {
+    compressionLevel: 'none' | 'moderate' | 'aggressive';
+    hierarchyEnabled: boolean;
+    criticalRulesCount: number;
+    includeDODONT: boolean;
+    includeTroubleshooting: boolean;
+}
+export declare class LLMOptimizedInstructionGenerator {
+    private config;
+    constructor(config?: Partial<OptimizationConfig>);
+    /**
+     * Generate LLM-optimized custom instructions
+     */
+    generateInstructions(projectInfo: ProjectInfo): string;
+    private generateHeader;
+    private generateCriticalRules;
+    private generateProjectOverview;
+    private generateCodePatterns;
+    private generateWorkflow;
+    private generateTroubleshooting;
+    /**
+     * Generate project index JSON
+     */
+    generateIndex(projectInfo: ProjectInfo): string;
+}
+export {};

package/dist/utils/llm-optimized-instruction-generator.js

@@ -0,0 +1,296 @@
+/**
+ * LLM-Optimized Instruction Generator
+ * Generates token-efficient, comprehension-optimized project instructions
+ */
+export class LLMOptimizedInstructionGenerator {
+    config;
+    constructor(config = {}) {
+        this.config = {
+            compressionLevel: config.compressionLevel || 'moderate',
+            hierarchyEnabled: config.hierarchyEnabled ?? true,
+            criticalRulesCount: config.criticalRulesCount || 5,
+            includeDODONT: config.includeDODONT ?? true,
+            includeTroubleshooting: config.includeTroubleshooting ?? true,
+        };
+    }
+    /**
+     * Generate LLM-optimized custom instructions
+     */
+    generateInstructions(projectInfo) {
+        const sections = [];
+        // Header (compressed)
+        sections.push(this.generateHeader(projectInfo));
+        // Critical Rules (front-loaded)
+        if (this.config.hierarchyEnabled) {
+            sections.push(this.generateCriticalRules(projectInfo));
+        }
+        // Project Overview (compressed)
+        sections.push(this.generateProjectOverview(projectInfo));
+        // Code Patterns with DO/DON'T
+        sections.push(this.generateCodePatterns(projectInfo));
+        // Development Workflow (compressed, tool-agnostic)
+        sections.push(this.generateWorkflow(projectInfo));
+        // Troubleshooting
+        if (this.config.includeTroubleshooting) {
+            sections.push(this.generateTroubleshooting(projectInfo));
+        }
+        return sections.join('\n\n---\n\n');
+    }
+    generateHeader(projectInfo) {
+        // Compressed header - remove "Custom Instructions for AX CLI"
+        const version = projectInfo.version ? ` v${projectInfo.version}` : '';
+        const stack = projectInfo.techStack.length > 0
+            ? `\n**Stack:** ${projectInfo.techStack.join(', ')}`
+            : '';
+        return `# ${projectInfo.name} - Quick Reference
+
+**Type:** ${projectInfo.projectType} | **Lang:** ${projectInfo.primaryLanguage}${version ? ` | **Ver:** ${version}` : ''}${stack}`;
+    }
+    generateCriticalRules(projectInfo) {
+        const rules = [];
+        // Rule 1: ESM imports (if applicable)
+        if (projectInfo.conventions.importExtension === '.js') {
+            rules.push('**ESM Imports:** Always use `.js` extension: `import { x } from \'./y.js\'`');
+        }
+        // Rule 2: Validation (if applicable)
+        if (projectInfo.conventions.validation) {
+            rules.push(`**Validation:** Use ${projectInfo.conventions.validation} for all external inputs`);
+        }
+        // Rule 3: TypeScript types (if applicable)
+        if (projectInfo.primaryLanguage === 'TypeScript') {
+            rules.push('**Types:** Explicit return types required on all functions');
+        }
+        // Rule 4: Testing coverage
+        if (projectInfo.scripts.test) {
+            rules.push('**Testing:** 80%+ coverage, test error paths');
+        }
+        // Rule 5: Module system
+        if (projectInfo.conventions.moduleSystem === 'esm') {
+            rules.push('**Modules:** Use `import/export` (not `require/module.exports`)');
+        }
+        // Take only top N rules
+        const topRules = rules.slice(0, this.config.criticalRulesCount);
+        if (topRules.length === 0) {
+            return '';
+        }
+        return `## 🎯 Critical Rules\n\n${topRules.map((rule, i) => `${i + 1}. ${rule}`).join('\n')}`;
+    }
+    generateProjectOverview(projectInfo) {
+        const parts = [`## 📋 Project Overview`];
+        // Tech details (compressed)
+        const details = [];
+        if (projectInfo.entryPoint) {
+            details.push(`**Entry:** \`${projectInfo.entryPoint}\``);
+        }
+        if (projectInfo.packageManager) {
+            details.push(`**PM:** ${projectInfo.packageManager}`);
+        }
+        if (projectInfo.conventions.moduleSystem) {
+            details.push(`**Module:** ${projectInfo.conventions.moduleSystem.toUpperCase()}`);
+        }
+        if (details.length > 0) {
+            parts.push(details.join(' | '));
+        }
+        // Directories (compressed)
+        const dirs = [];
+        if (projectInfo.directories.source) {
+            dirs.push(`- \`${projectInfo.directories.source}/\` - Source code`);
+        }
+        if (projectInfo.directories.tests) {
+            dirs.push(`- \`${projectInfo.directories.tests}/\` - Tests`);
+        }
+        if (projectInfo.directories.tools) {
+            dirs.push(`- \`${projectInfo.directories.tools}/\` - Tools`);
+        }
+        // Add typical subdirectories for CLI/API
+        if (projectInfo.projectType === 'cli' || projectInfo.projectType === 'api') {
+            if (projectInfo.directories.source) {
+                dirs.push(`- \`${projectInfo.directories.source}/commands/\` - Commands`);
+                dirs.push(`- \`${projectInfo.directories.source}/utils/\` - Utilities`);
+            }
+        }
+        if (dirs.length > 0) {
+            parts.push('\n**Directories:**\n' + dirs.join('\n'));
+        }
+        return parts.join('\n\n');
+    }
+    generateCodePatterns(projectInfo) {
+        let content = '## 🔧 Code Patterns';
+        // TypeScript patterns with DO/DON'T
+        if (projectInfo.primaryLanguage === 'TypeScript' && this.config.includeDODONT) {
+            content += '\n\n### TypeScript\n';
+            content += '\n✅ **DO:**\n';
+            content += '```typescript\n';
+            content += '// Explicit types\n';
+            content += 'function process(x: string): Promise<Result> { }\n';
+            if (projectInfo.conventions.importExtension === '.js') {
+                content += '\n// ESM imports with .js extension\n';
+                content += 'import { foo } from \'./bar.js\';\n';
+            }
+            content += '```\n';
+            content += '\n❌ **DON\'T:**\n';
+            content += '```typescript\n';
+            content += '// No any types\n';
+            content += 'function process(x: any) { }  // ❌\n';
+            if (projectInfo.conventions.importExtension === '.js') {
+                content += '\n// Missing .js extension\n';
+                content += 'import { foo } from \'./bar\';  // ❌\n';
+            }
+            content += '```';
+        }
+        // Validation patterns (if applicable)
+        if (projectInfo.conventions.validation && this.config.includeDODONT) {
+            content += `\n\n### Validation (${projectInfo.conventions.validation})\n`;
+            content += '\n✅ **DO:**\n';
+            content += '```typescript\n';
+            content += `const result = schema.safeParse(data);\n`;
+            content += 'if (!result.success) {\n';
+            content += '  return { success: false, error: result.error };\n';
+            content += '}\n';
+            content += '```';
+        }
+        // Project-specific patterns based on type
+        if (projectInfo.projectType === 'cli') {
+            content += '\n\n### CLI Commands\n';
+            content += 'Commands should:\n';
+            content += '- Accept options via flags (`-f, --flag <value>`)\n';
+            content += '- Validate input before execution\n';
+            content += '- Provide clear error messages\n';
+            content += '- Return exit codes (0 = success, 1+ = error)';
+        }
+        else if (projectInfo.projectType === 'api') {
+            content += '\n\n### API Endpoints\n';
+            content += 'Endpoints should:\n';
+            content += '- Validate request body/params\n';
+            content += '- Use proper HTTP status codes\n';
+            content += '- Handle errors with consistent format\n';
+            content += '- Document with OpenAPI/Swagger';
+        }
+        else if (projectInfo.projectType === 'library') {
+            content += '\n\n### Library API\n';
+            content += 'Public API should:\n';
+            content += '- Have clear, typed interfaces\n';
+            content += '- Validate all inputs\n';
+            content += '- Avoid breaking changes\n';
+            content += '- Document all exports';
+        }
+        return content;
+    }
+    generateWorkflow(projectInfo) {
+        let workflow = '## 🔄 Workflow';
+        // Before (compressed, tool-agnostic)
+        workflow += '\n\n**Before:**\n';
+        workflow += '- Read files to understand implementation\n';
+        workflow += '- Search for related patterns\n';
+        workflow += '- Review tests for expected behavior';
+        // Changes (compressed)
+        workflow += '\n\n**Changes:**\n';
+        workflow += '- Edit existing files (never recreate)\n';
+        workflow += '- Keep changes focused and atomic\n';
+        workflow += '- Preserve code style\n';
+        workflow += '- Update tests when changing functionality';
+        // After (compressed with actual commands)
+        const afterSteps = [];
+        if (projectInfo.scripts.lint) {
+            afterSteps.push(`Lint: \`${projectInfo.scripts.lint}\``);
+        }
+        if (projectInfo.scripts.test) {
+            afterSteps.push(`Test: \`${projectInfo.scripts.test}\``);
+        }
+        if (projectInfo.scripts.build) {
+            afterSteps.push(`Build: \`${projectInfo.scripts.build}\``);
+        }
+        if (afterSteps.length > 0) {
+            workflow += '\n\n**After:**\n';
+            workflow += afterSteps.map((step, i) => `${i + 1}. ${step}`).join('\n');
+        }
+        // Quick commands (compressed)
+        if (projectInfo.packageManager && Object.keys(projectInfo.scripts).length > 0) {
+            workflow += '\n\n**Quick Commands:**\n```bash\n';
+            const pm = projectInfo.packageManager;
+            const run = pm === 'npm' ? 'npm run' : pm;
+            const test = pm === 'npm' ? 'npm' : pm;
+            if (projectInfo.scripts.dev) {
+                workflow += `${run} dev     # Development\n`;
+            }
+            if (projectInfo.scripts.test) {
+                workflow += `${test} test    # Run tests\n`;
+            }
+            if (projectInfo.scripts.build) {
+                workflow += `${run} build   # Production build\n`;
+            }
+            workflow += '```';
+        }
+        return workflow;
+    }
+    generateTroubleshooting(projectInfo) {
+        let content = '## 🐛 Troubleshooting';
+        const issues = [];
+        // ESM import issues
+        if (projectInfo.conventions.importExtension === '.js') {
+            issues.push({
+                problem: '"Module not found" errors',
+                solution: 'Add `.js` extension to imports (ESM requirement)',
+                code: `// ✅ Correct\nimport { x } from './y.js';\n\n// ❌ Wrong\nimport { x } from './y';  // Missing .js`,
+            });
+        }
+        // Validation errors
+        if (projectInfo.conventions.validation) {
+            issues.push({
+                problem: `${projectInfo.conventions.validation} validation errors`,
+                solution: 'Use `.safeParse()` for detailed error messages. Check schema matches data structure.',
+            });
+        }
+        // Test failures
+        if (projectInfo.conventions.testFramework) {
+            issues.push({
+                problem: 'Tests fail locally but pass in CI',
+                solution: `Check Node version, clear node_modules, check environment-specific code`,
+            });
+        }
+        // TypeScript errors
+        if (projectInfo.primaryLanguage === 'TypeScript') {
+            issues.push({
+                problem: 'TypeScript compilation errors',
+                solution: 'Check `tsconfig.json` settings, ensure all types are imported, verify `moduleResolution`',
+            });
+        }
+        if (issues.length === 0) {
+            return '';
+        }
+        for (const issue of issues) {
+            content += `\n\n### ${issue.problem}\n`;
+            content += `**Solution:** ${issue.solution}`;
+            if (issue.code) {
+                content += `\n\`\`\`typescript\n${issue.code}\n\`\`\``;
+            }
+        }
+        return content;
+    }
+    /**
+     * Generate project index JSON
+     */
+    generateIndex(projectInfo) {
+        const index = {
+            projectName: projectInfo.name,
+            version: projectInfo.version,
+            primaryLanguage: projectInfo.primaryLanguage,
+            techStack: projectInfo.techStack,
+            projectType: projectInfo.projectType,
+            entryPoint: projectInfo.entryPoint,
+            directories: projectInfo.directories,
+            keyFiles: Object.keys(projectInfo.keyFiles),
+            conventions: {
+                moduleSystem: projectInfo.conventions.moduleSystem,
+                importExtension: projectInfo.conventions.importExtension,
+                testFramework: projectInfo.conventions.testFramework,
+                validation: projectInfo.conventions.validation,
+            },
+            scripts: projectInfo.scripts,
+            packageManager: projectInfo.packageManager,
+            lastAnalyzed: projectInfo.lastAnalyzed,
+        };
+        return JSON.stringify(index, null, 2);
+    }
+}
+//# sourceMappingURL=llm-optimized-instruction-generator.js.map

package/dist/utils/llm-optimized-instruction-generator.js.map

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

package/dist/utils/onboarding-manager.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Onboarding Manager - First-run detection and state management
+ */
+export interface OnboardingState {
+    isFirstRun: boolean;
+    setupCompleted: boolean;
+    completedAt?: string;
+    version: string;
+}
+export declare class OnboardingManager {
+    private static readonly FIRST_RUN_MARKER;
+    private static readonly USER_CONFIG_DIR;
+    /**
+     * Get the user's AX CLI configuration directory
+     */
+    private static getUserConfigDir;
+    /**
+     * Get the path to the first-run marker file
+     */
+    private static getMarkerPath;
+    /**
+     * Detect if this is the user's first run of AX CLI
+     */
+    static detectFirstRun(): boolean;
+    /**
+     * Mark onboarding as completed
+     */
+    static markCompleted(): void;
+    /**
+     * Get current onboarding state
+     */
+    static getCurrentState(): OnboardingState;
+    /**
+     * Reset onboarding state (useful for testing)
+     */
+    static resetOnboarding(): void;
+    /**
+     * Check if welcome screen should be shown
+     */
+    static shouldShowWelcome(): boolean;
+    /**
+     * Get current CLI version
+     */
+    private static getVersion;
+}

package/dist/utils/onboarding-manager.js

@@ -0,0 +1,130 @@
+/**
+ * Onboarding Manager - First-run detection and state management
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { fileURLToPath } from 'url';
+import { parseJsonFile } from './json-utils.js';
+export class OnboardingManager {
+    static FIRST_RUN_MARKER = '.first-run-complete';
+    static USER_CONFIG_DIR = '.ax-cli';
+    /**
+     * Get the user's AX CLI configuration directory
+     */
+    static getUserConfigDir() {
+        return path.join(os.homedir(), OnboardingManager.USER_CONFIG_DIR);
+    }
+    /**
+     * Get the path to the first-run marker file
+     */
+    static getMarkerPath() {
+        return path.join(OnboardingManager.getUserConfigDir(), OnboardingManager.FIRST_RUN_MARKER);
+    }
+    /**
+     * Detect if this is the user's first run of AX CLI
+     */
+    static detectFirstRun() {
+        const markerPath = OnboardingManager.getMarkerPath();
+        return !fs.existsSync(markerPath);
+    }
+    /**
+     * Mark onboarding as completed
+     */
+    static markCompleted() {
+        const configDir = OnboardingManager.getUserConfigDir();
+        const markerPath = OnboardingManager.getMarkerPath();
+        // Create config directory if it doesn't exist
+        if (!fs.existsSync(configDir)) {
+            fs.mkdirSync(configDir, { recursive: true });
+        }
+        // Create marker file with timestamp
+        const state = {
+            isFirstRun: false,
+            setupCompleted: true,
+            completedAt: new Date().toISOString(),
+            version: this.getVersion(),
+        };
+        // Atomic write using temp file
+        const tmpPath = `${markerPath}.tmp`;
+        try {
+            fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf-8');
+            fs.renameSync(tmpPath, markerPath); // Atomic on POSIX systems
+        }
+        catch (error) {
+            // Cleanup temp file on error
+            if (fs.existsSync(tmpPath)) {
+                try {
+                    fs.unlinkSync(tmpPath);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get current onboarding state
+     */
+    static getCurrentState() {
+        const markerPath = OnboardingManager.getMarkerPath();
+        if (!fs.existsSync(markerPath)) {
+            return {
+                isFirstRun: true,
+                setupCompleted: false,
+                version: this.getVersion(),
+            };
+        }
+        const parseResult = parseJsonFile(markerPath);
+        if (!parseResult.success) {
+            // If marker file is corrupted, treat as first run
+            return {
+                isFirstRun: true,
+                setupCompleted: false,
+                version: this.getVersion(),
+            };
+        }
+        return parseResult.data;
+    }
+    /**
+     * Reset onboarding state (useful for testing)
+     */
+    static resetOnboarding() {
+        const markerPath = OnboardingManager.getMarkerPath();
+        if (fs.existsSync(markerPath)) {
+            fs.unlinkSync(markerPath);
+        }
+    }
+    /**
+     * Check if welcome screen should be shown
+     */
+    static shouldShowWelcome() {
+        return OnboardingManager.detectFirstRun();
+    }
+    /**
+     * Get current CLI version
+     */
+    static getVersion() {
+        try {
+            // Use import.meta.url to find the actual CLI installation path
+            const currentModulePath = fileURLToPath(import.meta.url);
+            const cliRootPath = path.join(path.dirname(currentModulePath), '../..');
+            const packageJsonPath = path.join(cliRootPath, 'package.json');
+            if (fs.existsSync(packageJsonPath)) {
+                const parseResult = parseJsonFile(packageJsonPath);
+                if (parseResult.success) {
+                    const pkg = parseResult.data;
+                    if (pkg && typeof pkg === 'object' && 'version' in pkg && typeof pkg.version === 'string') {
+                        return pkg.version;
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+        return '0.0.0';
+    }
+}
+//# sourceMappingURL=onboarding-manager.js.map

package/dist/utils/onboarding-manager.js.map

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

package/dist/utils/path-utils.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Cross-platform path utility functions
+ *
+ * This module provides utilities for handling file paths consistently
+ * across different operating systems (Windows, macOS, Linux).
+ *
+ * @module path-utils
+ */
+/**
+ * Normalize path separators to forward slashes (for display and logging)
+ *
+ * This function converts all path separators to forward slashes, which is
+ * useful for consistent display across platforms and for comparison in tests.
+ *
+ * @example
+ * // Windows
+ * normalizePath('C:\\Users\\foo\\bar') // => 'C:/Users/foo/bar'
+ *
+ * // Unix
+ * normalizePath('/Users/foo/bar') // => '/Users/foo/bar'
+ *
+ * @param filePath - The path to normalize
+ * @returns Path with forward slashes (empty string if input is falsy)
+ */
+export declare function normalizePath(filePath: string): string;
+/**
+ * Convert path to platform-native format (for filesystem operations)
+ *
+ * This function normalizes the path to use the platform's native separator,
+ * which is necessary for filesystem operations.
+ *
+ * @example
+ * // Windows
+ * platformPath('foo/bar/baz') // => 'foo\\bar\\baz'
+ *
+ * // Unix
+ * platformPath('foo/bar/baz') // => 'foo/bar/baz'
+ *
+ * @param filePath - The path to convert
+ * @returns Path with platform-native separators (empty string if input is falsy)
+ */
+export declare function platformPath(filePath: string): string;
+/**
+ * Check if running on Windows
+ *
+ * @returns True if running on Windows platform
+ */
+export declare function isWindows(): boolean;
+/**
+ * Compare two paths for equality (ignoring separator differences)
+ *
+ * This function compares two paths by normalizing both to forward slashes
+ * and then comparing case-insensitively on Windows.
+ *
+ * @example
+ * // Windows
+ * pathsEqual('foo/bar', 'foo\\bar') // => true
+ * pathsEqual('Foo/Bar', 'foo/bar') // => true
+ *
+ * // Unix
+ * pathsEqual('foo/bar', 'foo/bar') // => true
+ * pathsEqual('Foo/Bar', 'foo/bar') // => false
+ *
+ * @param path1 - First path to compare
+ * @param path2 - Second path to compare
+ * @returns True if paths are equal
+ */
+export declare function pathsEqual(path1: string, path2: string): boolean;
+/**
+ * Check if a path contains a segment (cross-platform)
+ *
+ * This function checks if a full path contains a specific segment,
+ * normalizing both paths before comparison.
+ *
+ * @example
+ * pathContains('/foo/bar/baz', 'bar/baz') // => true
+ * pathContains('C:\\foo\\bar', 'bar') // => true
+ *
+ * @param fullPath - Full path to search in
+ * @param segment - Segment to search for
+ * @returns True if fullPath contains segment
+ */
+export declare function pathContains(fullPath: string, segment: string): boolean;