@defai.digital/ax-cli 3.0.2 → 3.1.0

package/dist/memory/schemas.d.ts

@@ -0,0 +1,316 @@
+/**
+ * Zod schemas for Project Memory validation
+ *
+ * Provides runtime validation for memory.json structure
+ */
+import { z } from 'zod';
+/**
+ * Schema for directory configuration
+ */
+export declare const DirectoryConfigSchema: z.ZodObject<{
+    path: z.ZodString;
+    max_depth: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    max_depth: number;
+}, {
+    path: string;
+    max_depth: number;
+}>;
+/**
+ * Schema for source configuration
+ */
+export declare const SourceConfigSchema: z.ZodObject<{
+    directories: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        max_depth: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        max_depth: number;
+    }, {
+        path: string;
+        max_depth: number;
+    }>, "many">;
+    files: z.ZodArray<z.ZodString, "many">;
+    ignore: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    directories: {
+        path: string;
+        max_depth: number;
+    }[];
+    files: string[];
+    ignore: string[];
+}, {
+    directories: {
+        path: string;
+        max_depth: number;
+    }[];
+    files: string[];
+    ignore: string[];
+}>;
+/**
+ * Schema for context sections token distribution
+ */
+export declare const ContextSectionsSchema: z.ZodObject<{
+    structure: z.ZodOptional<z.ZodNumber>;
+    readme: z.ZodOptional<z.ZodNumber>;
+    config: z.ZodOptional<z.ZodNumber>;
+    patterns: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    structure?: number | undefined;
+    readme?: number | undefined;
+    config?: number | undefined;
+    patterns?: number | undefined;
+}, {
+    structure?: number | undefined;
+    readme?: number | undefined;
+    config?: number | undefined;
+    patterns?: number | undefined;
+}>;
+/**
+ * Schema for generated context data
+ */
+export declare const ContextDataSchema: z.ZodObject<{
+    formatted: z.ZodString;
+    token_estimate: z.ZodNumber;
+    sections: z.ZodObject<{
+        structure: z.ZodOptional<z.ZodNumber>;
+        readme: z.ZodOptional<z.ZodNumber>;
+        config: z.ZodOptional<z.ZodNumber>;
+        patterns: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        structure?: number | undefined;
+        readme?: number | undefined;
+        config?: number | undefined;
+        patterns?: number | undefined;
+    }, {
+        structure?: number | undefined;
+        readme?: number | undefined;
+        config?: number | undefined;
+        patterns?: number | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    sections: {
+        structure?: number | undefined;
+        readme?: number | undefined;
+        config?: number | undefined;
+        patterns?: number | undefined;
+    };
+    formatted: string;
+    token_estimate: number;
+}, {
+    sections: {
+        structure?: number | undefined;
+        readme?: number | undefined;
+        config?: number | undefined;
+        patterns?: number | undefined;
+    };
+    formatted: string;
+    token_estimate: number;
+}>;
+/**
+ * Schema for cache statistics
+ */
+export declare const CacheStatsSchema: z.ZodObject<{
+    last_cached_tokens: z.ZodOptional<z.ZodNumber>;
+    last_prompt_tokens: z.ZodOptional<z.ZodNumber>;
+    total_tokens_saved: z.ZodOptional<z.ZodNumber>;
+    usage_count: z.ZodOptional<z.ZodNumber>;
+    last_used_at: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    last_cached_tokens?: number | undefined;
+    last_prompt_tokens?: number | undefined;
+    total_tokens_saved?: number | undefined;
+    usage_count?: number | undefined;
+    last_used_at?: string | undefined;
+}, {
+    last_cached_tokens?: number | undefined;
+    last_prompt_tokens?: number | undefined;
+    total_tokens_saved?: number | undefined;
+    usage_count?: number | undefined;
+    last_used_at?: string | undefined;
+}>;
+/**
+ * Main Project Memory schema
+ */
+export declare const ProjectMemorySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    project_root: z.ZodString;
+    content_hash: z.ZodString;
+    source: z.ZodObject<{
+        directories: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            max_depth: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            max_depth: number;
+        }, {
+            path: string;
+            max_depth: number;
+        }>, "many">;
+        files: z.ZodArray<z.ZodString, "many">;
+        ignore: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        directories: {
+            path: string;
+            max_depth: number;
+        }[];
+        files: string[];
+        ignore: string[];
+    }, {
+        directories: {
+            path: string;
+            max_depth: number;
+        }[];
+        files: string[];
+        ignore: string[];
+    }>;
+    context: z.ZodObject<{
+        formatted: z.ZodString;
+        token_estimate: z.ZodNumber;
+        sections: z.ZodObject<{
+            structure: z.ZodOptional<z.ZodNumber>;
+            readme: z.ZodOptional<z.ZodNumber>;
+            config: z.ZodOptional<z.ZodNumber>;
+            patterns: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            structure?: number | undefined;
+            readme?: number | undefined;
+            config?: number | undefined;
+            patterns?: number | undefined;
+        }, {
+            structure?: number | undefined;
+            readme?: number | undefined;
+            config?: number | undefined;
+            patterns?: number | undefined;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        sections: {
+            structure?: number | undefined;
+            readme?: number | undefined;
+            config?: number | undefined;
+            patterns?: number | undefined;
+        };
+        formatted: string;
+        token_estimate: number;
+    }, {
+        sections: {
+            structure?: number | undefined;
+            readme?: number | undefined;
+            config?: number | undefined;
+            patterns?: number | undefined;
+        };
+        formatted: string;
+        token_estimate: number;
+    }>;
+    stats: z.ZodOptional<z.ZodObject<{
+        last_cached_tokens: z.ZodOptional<z.ZodNumber>;
+        last_prompt_tokens: z.ZodOptional<z.ZodNumber>;
+        total_tokens_saved: z.ZodOptional<z.ZodNumber>;
+        usage_count: z.ZodOptional<z.ZodNumber>;
+        last_used_at: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        last_cached_tokens?: number | undefined;
+        last_prompt_tokens?: number | undefined;
+        total_tokens_saved?: number | undefined;
+        usage_count?: number | undefined;
+        last_used_at?: string | undefined;
+    }, {
+        last_cached_tokens?: number | undefined;
+        last_prompt_tokens?: number | undefined;
+        total_tokens_saved?: number | undefined;
+        usage_count?: number | undefined;
+        last_used_at?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    created_at: string;
+    updated_at: string;
+    project_root: string;
+    content_hash: string;
+    source: {
+        directories: {
+            path: string;
+            max_depth: number;
+        }[];
+        files: string[];
+        ignore: string[];
+    };
+    context: {
+        sections: {
+            structure?: number | undefined;
+            readme?: number | undefined;
+            config?: number | undefined;
+            patterns?: number | undefined;
+        };
+        formatted: string;
+        token_estimate: number;
+    };
+    stats?: {
+        last_cached_tokens?: number | undefined;
+        last_prompt_tokens?: number | undefined;
+        total_tokens_saved?: number | undefined;
+        usage_count?: number | undefined;
+        last_used_at?: string | undefined;
+    } | undefined;
+}, {
+    version: 1;
+    created_at: string;
+    updated_at: string;
+    project_root: string;
+    content_hash: string;
+    source: {
+        directories: {
+            path: string;
+            max_depth: number;
+        }[];
+        files: string[];
+        ignore: string[];
+    };
+    context: {
+        sections: {
+            structure?: number | undefined;
+            readme?: number | undefined;
+            config?: number | undefined;
+            patterns?: number | undefined;
+        };
+        formatted: string;
+        token_estimate: number;
+    };
+    stats?: {
+        last_cached_tokens?: number | undefined;
+        last_prompt_tokens?: number | undefined;
+        total_tokens_saved?: number | undefined;
+        usage_count?: number | undefined;
+        last_used_at?: string | undefined;
+    } | undefined;
+}>;
+/**
+ * Inferred TypeScript type from schema
+ */
+export type ProjectMemorySchema = z.infer<typeof ProjectMemorySchema>;
+/**
+ * Safe validation result type
+ */
+export type ValidationResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Safely validate project memory data
+ * Returns a discriminated union for easy error handling
+ */
+export declare function safeValidateProjectMemory(data: unknown): ValidationResult<ProjectMemorySchema>;
+/**
+ * Validate partial memory update (for stats updates)
+ */
+export declare function safeValidateCacheStats(data: unknown): ValidationResult<z.infer<typeof CacheStatsSchema>>;
+/**
+ * Validate source configuration
+ */
+export declare function safeValidateSourceConfig(data: unknown): ValidationResult<z.infer<typeof SourceConfigSchema>>;

package/dist/memory/schemas.js

@@ -0,0 +1,103 @@
+/**
+ * Zod schemas for Project Memory validation
+ *
+ * Provides runtime validation for memory.json structure
+ */
+import { z } from 'zod';
+/**
+ * Schema for directory configuration
+ */
+export const DirectoryConfigSchema = z.object({
+    path: z.string().min(1, 'Directory path cannot be empty'),
+    max_depth: z.number().int().min(1).max(10),
+});
+/**
+ * Schema for source configuration
+ */
+export const SourceConfigSchema = z.object({
+    directories: z.array(DirectoryConfigSchema),
+    files: z.array(z.string()),
+    ignore: z.array(z.string()),
+});
+/**
+ * Schema for context sections token distribution
+ */
+export const ContextSectionsSchema = z.object({
+    structure: z.number().int().min(0).optional(),
+    readme: z.number().int().min(0).optional(),
+    config: z.number().int().min(0).optional(),
+    patterns: z.number().int().min(0).optional(),
+});
+/**
+ * Schema for generated context data
+ */
+export const ContextDataSchema = z.object({
+    formatted: z.string(),
+    token_estimate: z.number().int().min(0),
+    sections: ContextSectionsSchema,
+});
+/**
+ * Schema for cache statistics
+ */
+export const CacheStatsSchema = z.object({
+    last_cached_tokens: z.number().int().min(0).optional(),
+    last_prompt_tokens: z.number().int().min(0).optional(),
+    total_tokens_saved: z.number().int().min(0).optional(),
+    usage_count: z.number().int().min(0).optional(),
+    last_used_at: z.string().datetime().optional(),
+});
+/**
+ * Main Project Memory schema
+ */
+export const ProjectMemorySchema = z.object({
+    version: z.literal(1),
+    created_at: z.string().datetime(),
+    updated_at: z.string().datetime(),
+    project_root: z.string().min(1),
+    content_hash: z.string().regex(/^sha256:[a-f0-9]{64}$/, 'Content hash must be in format: sha256:<64 hex chars>'),
+    source: SourceConfigSchema,
+    context: ContextDataSchema,
+    stats: CacheStatsSchema.optional(),
+});
+/**
+ * Safely validate project memory data
+ * Returns a discriminated union for easy error handling
+ */
+export function safeValidateProjectMemory(data) {
+    const result = ProjectMemorySchema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    // Format error message
+    const errors = result.error.errors
+        .map((e) => `${e.path.join('.')}: ${e.message}`)
+        .join('; ');
+    return { success: false, error: errors };
+}
+/**
+ * Validate partial memory update (for stats updates)
+ */
+export function safeValidateCacheStats(data) {
+    const result = CacheStatsSchema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    const errors = result.error.errors
+        .map((e) => `${e.path.join('.')}: ${e.message}`)
+        .join('; ');
+    return { success: false, error: errors };
+}
+/**
+ * Validate source configuration
+ */
+export function safeValidateSourceConfig(data) {
+    const result = SourceConfigSchema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    const errors = result.error.errors
+        .map((e) => `${e.path.join('.')}: ${e.message}`)
+        .join('; ');
+    return { success: false, error: errors };
+}
+//# sourceMappingURL=schemas.js.map

package/dist/memory/schemas.js.map

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

package/dist/memory/stats-collector.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Stats Collector - Collects and reports cache statistics
+ *
+ * Tracks z.ai cache performance by recording cached_tokens
+ * from API responses and calculating efficiency metrics.
+ */
+import type { CacheStats } from './types.js';
+/**
+ * Formatted statistics for display
+ */
+export interface FormattedStats {
+    /** Human-readable stats text */
+    text: string;
+    /** Cache hit rate percentage (0-100) */
+    cacheRate: number;
+    /** Total tokens saved through caching */
+    tokensSaved: number;
+    /** Number of API calls */
+    usageCount: number;
+    /** Estimated cost savings (rough estimate) */
+    estimatedSavings: number;
+}
+/**
+ * StatsCollector - Manages cache statistics
+ */
+export declare class StatsCollector {
+    private store;
+    constructor(projectRoot?: string);
+    /**
+     * Record API response statistics
+     *
+     * @param promptTokens - Total prompt tokens from response
+     * @param cachedTokens - Cached tokens from response (from usage.prompt_tokens_details.cached_tokens)
+     */
+    recordResponse(promptTokens: number, cachedTokens: number): void;
+    /**
+     * Get raw statistics
+     */
+    getStats(): CacheStats | null;
+    /**
+     * Calculate cache hit rate from last request
+     */
+    getLastCacheRate(): number;
+    /**
+     * Calculate estimated cost savings
+     */
+    getEstimatedSavings(): number;
+    /**
+     * Get formatted statistics for display
+     */
+    getFormattedStats(): FormattedStats | null;
+    /**
+     * Format a brief cache status line for verbose output
+     */
+    formatBriefStatus(promptTokens: number, cachedTokens: number): string;
+    /**
+     * Check if caching appears to be working
+     * Returns a warning message if cache hits are consistently zero
+     */
+    checkCacheHealth(): string | null;
+    /**
+     * Reset statistics (keeps memory content, only clears stats)
+     */
+    resetStats(): boolean;
+}
+/**
+ * Get the default stats collector instance
+ */
+export declare function getStatsCollector(projectRoot?: string): StatsCollector;
+/**
+ * Reset the default collector (mainly for testing)
+ */
+export declare function resetDefaultCollector(): void;

package/dist/memory/stats-collector.js

@@ -0,0 +1,170 @@
+/**
+ * Stats Collector - Collects and reports cache statistics
+ *
+ * Tracks z.ai cache performance by recording cached_tokens
+ * from API responses and calculating efficiency metrics.
+ */
+import { ContextStore } from './context-store.js';
+/**
+ * Token pricing constants (rough estimates for z.ai)
+ * These are approximate and should be updated based on actual pricing
+ */
+const PRICING = {
+    /** Cost per 1K input tokens (USD) */
+    INPUT_PER_1K: 0.002,
+    /** Cost per 1K cached tokens (50% discount) */
+    CACHED_PER_1K: 0.001,
+};
+/**
+ * StatsCollector - Manages cache statistics
+ */
+export class StatsCollector {
+    store;
+    constructor(projectRoot = process.cwd()) {
+        this.store = new ContextStore(projectRoot);
+    }
+    /**
+     * Record API response statistics
+     *
+     * @param promptTokens - Total prompt tokens from response
+     * @param cachedTokens - Cached tokens from response (from usage.prompt_tokens_details.cached_tokens)
+     */
+    recordResponse(promptTokens, cachedTokens) {
+        // Use the store's recordUsage method
+        this.store.recordUsage(promptTokens, cachedTokens);
+    }
+    /**
+     * Get raw statistics
+     */
+    getStats() {
+        const result = this.store.load();
+        if (!result.success) {
+            return null;
+        }
+        return result.data.stats || null;
+    }
+    /**
+     * Calculate cache hit rate from last request
+     */
+    getLastCacheRate() {
+        const stats = this.getStats();
+        if (!stats || !stats.last_prompt_tokens || !stats.last_cached_tokens) {
+            return 0;
+        }
+        return Math.round((stats.last_cached_tokens / stats.last_prompt_tokens) * 100);
+    }
+    /**
+     * Calculate estimated cost savings
+     */
+    getEstimatedSavings() {
+        const stats = this.getStats();
+        if (!stats || !stats.total_tokens_saved) {
+            return 0;
+        }
+        // Savings = tokens_saved * (regular_price - cached_price)
+        const savingsPerToken = (PRICING.INPUT_PER_1K - PRICING.CACHED_PER_1K) / 1000;
+        return stats.total_tokens_saved * savingsPerToken;
+    }
+    /**
+     * Get formatted statistics for display
+     */
+    getFormattedStats() {
+        const stats = this.getStats();
+        if (!stats) {
+            return null;
+        }
+        const cacheRate = this.getLastCacheRate();
+        const tokensSaved = stats.total_tokens_saved || 0;
+        const usageCount = stats.usage_count || 0;
+        const estimatedSavings = this.getEstimatedSavings();
+        const lines = [
+            '📈 Cache Statistics',
+            '',
+            `   Usage count:      ${usageCount}`,
+            `   Last cache rate:  ${cacheRate}%`,
+            `   Tokens saved:     ${tokensSaved.toLocaleString()}`,
+            `   Est. savings:     $${estimatedSavings.toFixed(2)}`,
+        ];
+        if (stats.last_used_at) {
+            const lastUsed = new Date(stats.last_used_at);
+            lines.push(`   Last used:        ${lastUsed.toLocaleString()}`);
+        }
+        return {
+            text: lines.join('\n'),
+            cacheRate,
+            tokensSaved,
+            usageCount,
+            estimatedSavings,
+        };
+    }
+    /**
+     * Format a brief cache status line for verbose output
+     */
+    formatBriefStatus(promptTokens, cachedTokens) {
+        const rate = promptTokens > 0
+            ? Math.round((cachedTokens / promptTokens) * 100)
+            : 0;
+        return `cached: ${cachedTokens.toLocaleString()}/${promptTokens.toLocaleString()} tokens (${rate}% cache hit)`;
+    }
+    /**
+     * Check if caching appears to be working
+     * Returns a warning message if cache hits are consistently zero
+     */
+    checkCacheHealth() {
+        const stats = this.getStats();
+        if (!stats) {
+            return null;
+        }
+        // If we've had multiple uses but no cache hits, something might be wrong
+        if (stats.usage_count && stats.usage_count >= 3) {
+            if (!stats.total_tokens_saved || stats.total_tokens_saved === 0) {
+                return 'Warning: No cache hits detected after multiple uses. ' +
+                    'Consider running "ax memory refresh" to regenerate context.';
+            }
+            // Check for very low cache rate
+            const avgSavedPerUse = stats.total_tokens_saved / stats.usage_count;
+            if (avgSavedPerUse < 100) {
+                return 'Note: Cache hit rate is lower than expected. ' +
+                    'This may indicate context has changed frequently.';
+            }
+        }
+        return null;
+    }
+    /**
+     * Reset statistics (keeps memory content, only clears stats)
+     */
+    resetStats() {
+        const result = this.store.load();
+        if (!result.success) {
+            return false;
+        }
+        const memory = result.data;
+        memory.stats = undefined;
+        memory.updated_at = new Date().toISOString();
+        const saveResult = this.store.save(memory);
+        return saveResult.success;
+    }
+}
+/**
+ * Singleton instance
+ */
+let defaultCollector = null;
+/**
+ * Get the default stats collector instance
+ */
+export function getStatsCollector(projectRoot) {
+    if (projectRoot) {
+        return new StatsCollector(projectRoot);
+    }
+    if (!defaultCollector) {
+        defaultCollector = new StatsCollector();
+    }
+    return defaultCollector;
+}
+/**
+ * Reset the default collector (mainly for testing)
+ */
+export function resetDefaultCollector() {
+    defaultCollector = null;
+}
+//# sourceMappingURL=stats-collector.js.map

package/dist/memory/stats-collector.js.map

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