@vdntio/clai 0.1.0-alpha.1

package/dist/config/types.d.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+export declare const ProviderConfigSchema: z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    apiKeyEnv: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ProviderConfig = z.infer<typeof ProviderConfigSchema>;
+export declare const FileConfigSchema: z.ZodObject<{
+    provider: z.ZodOptional<z.ZodObject<{
+        default: z.ZodDefault<z.ZodString>;
+        fallback: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    context: z.ZodOptional<z.ZodObject<{
+        maxFiles: z.ZodDefault<z.ZodNumber>;
+        maxHistory: z.ZodDefault<z.ZodNumber>;
+        redactPaths: z.ZodDefault<z.ZodBoolean>;
+        redactUsername: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    safety: z.ZodOptional<z.ZodObject<{
+        confirmDangerous: z.ZodDefault<z.ZodBoolean>;
+        dangerousPatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    ui: z.ZodOptional<z.ZodObject<{
+        color: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            always: "always";
+            never: "never";
+        }>>;
+        debugLogFile: z.ZodOptional<z.ZodString>;
+        interactive: z.ZodDefault<z.ZodBoolean>;
+        promptTimeout: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    providers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        apiKey: z.ZodOptional<z.ZodString>;
+        apiKeyEnv: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        endpoint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type FileConfig = z.infer<typeof FileConfigSchema>;
+export interface Config {
+    provider: {
+        default: string;
+        fallback: string[];
+    };
+    context: {
+        maxFiles: number;
+        maxHistory: number;
+        redactPaths: boolean;
+        redactUsername: boolean;
+    };
+    safety: {
+        confirmDangerous: boolean;
+        dangerousPatterns: string[];
+    };
+    ui: {
+        color: 'auto' | 'always' | 'never';
+        debugLogFile?: string;
+        interactive: boolean;
+        numOptions: number;
+        promptTimeout: number;
+    };
+    providers: Record<string, ProviderConfig>;
+    model?: string;
+    providerName?: string;
+    quiet: boolean;
+    verbose: number;
+    force: boolean;
+    dryRun: boolean;
+    contextFile?: string;
+    offline: boolean;
+    debug: boolean;
+    debugFile?: string;
+    instruction: string;
+}

package/dist/config/types.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+// Provider configuration
+export const ProviderConfigSchema = z.object({
+    apiKey: z.string().optional(),
+    apiKeyEnv: z.string().optional(),
+    model: z.string().optional(),
+    endpoint: z.string().optional(),
+});
+// File config schema (from TOML files) - all nested objects are optional for partial configs
+export const FileConfigSchema = z.object({
+    provider: z
+        .object({
+        default: z.string().default('openrouter'),
+        fallback: z.array(z.string()).default([]),
+    })
+        .optional(),
+    context: z
+        .object({
+        maxFiles: z.number().int().min(1).max(100).default(10),
+        maxHistory: z.number().int().min(0).max(50).default(3),
+        redactPaths: z.boolean().default(false),
+        redactUsername: z.boolean().default(false),
+    })
+        .optional(),
+    safety: z
+        .object({
+        confirmDangerous: z.boolean().default(true),
+        dangerousPatterns: z.array(z.string()).default([]),
+    })
+        .optional(),
+    ui: z
+        .object({
+        color: z.enum(['auto', 'always', 'never']).default('auto'),
+        debugLogFile: z.string().optional(),
+        interactive: z.boolean().default(false),
+        promptTimeout: z.number().int().min(0).max(300000).default(30000),
+    })
+        .optional(),
+    providers: z.record(z.string(), ProviderConfigSchema).default({}),
+});

package/dist/context/directory.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Get current working directory
+ * Throws ContextError if cwd cannot be determined (fatal)
+ */
+export declare function getCwd(): string;
+/**
+ * Scan current directory and return list of files
+ * - Limited to maxFiles (sorted alphabetically)
+ * - Paths truncated to 80 chars (using basename if too long)
+ * - Optionally redacted for privacy
+ *
+ * On read error, returns empty array (non-fatal)
+ */
+export declare function scanDirectory(maxFiles: number, redactPaths: boolean): string[];
+/**
+ * Get redacted current working directory
+ */
+export declare function getRedactedCwd(redactPaths: boolean): string;

package/dist/context/directory.js

@@ -0,0 +1,71 @@
+// Directory context gathering
+import { readdirSync } from 'fs';
+import { basename } from 'path';
+import { ContextError } from './types.js';
+import { redactPath } from './redaction.js';
+const PATH_TRUNCATE_LENGTH = 80;
+/**
+ * Get current working directory
+ * Throws ContextError if cwd cannot be determined (fatal)
+ */
+export function getCwd() {
+    try {
+        return process.cwd();
+    }
+    catch (err) {
+        throw new ContextError(`Failed to get current working directory: ${err instanceof Error ? err.message : String(err)}`, 1);
+    }
+}
+/**
+ * Truncate a path to maximum length
+ * If path exceeds limit, return basename only
+ */
+function truncatePath(path, maxLength = PATH_TRUNCATE_LENGTH) {
+    if (path.length <= maxLength) {
+        return path;
+    }
+    return basename(path);
+}
+/**
+ * Scan current directory and return list of files
+ * - Limited to maxFiles (sorted alphabetically)
+ * - Paths truncated to 80 chars (using basename if too long)
+ * - Optionally redacted for privacy
+ *
+ * On read error, returns empty array (non-fatal)
+ */
+export function scanDirectory(maxFiles, redactPaths) {
+    const cwd = getCwd();
+    try {
+        // Read directory entries
+        const entries = readdirSync(cwd, { withFileTypes: true });
+        // Sort by name and take first maxFiles
+        const sorted = entries
+            .map((entry) => entry.name)
+            .sort((a, b) => a.localeCompare(b))
+            .slice(0, maxFiles);
+        // Apply truncation and redaction
+        return sorted.map((fileName) => {
+            const fullPath = `${cwd}/${fileName}`;
+            let result = truncatePath(fullPath);
+            if (redactPaths) {
+                result = redactPath(result);
+            }
+            return result;
+        });
+    }
+    catch {
+        // Non-fatal: return empty list on error
+        return [];
+    }
+}
+/**
+ * Get redacted current working directory
+ */
+export function getRedactedCwd(redactPaths) {
+    const cwd = getCwd();
+    if (redactPaths) {
+        return redactPath(cwd);
+    }
+    return cwd;
+}

package/dist/context/history.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Get shell history
+ * Returns last N commands based on detected shell
+ *
+ * - bash: ~/.bash_history
+ * - zsh: ~/.zsh_history
+ * - fish: ~/.local/share/fish/fish_history (read raw lines)
+ * - other: empty array
+ *
+ * On error or unsupported shell, returns empty array (non-fatal)
+ */
+export declare function getShellHistory(maxHistory: number): string[];
+/**
+ * Get detected shell name (for testing/debugging)
+ */
+export declare function getDetectedShell(): string | null;

package/dist/context/history.js

@@ -0,0 +1,89 @@
+// Shell history gathering
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+// History file paths by shell
+const HISTORY_PATHS = {
+    bash: ['.bash_history'],
+    zsh: ['.zsh_history'],
+    fish: ['.local/share/fish/fish_history'],
+    sh: ['.sh_history'],
+};
+/**
+ * Detect shell from SHELL environment variable
+ * Returns shell name (e.g., 'bash', 'zsh') or null if unknown
+ */
+function detectShell() {
+    const shell = process.env.SHELL || '';
+    if (!shell)
+        return null;
+    const shellName = shell.split('/').pop() || '';
+    // Check if we support this shell
+    if (HISTORY_PATHS[shellName]) {
+        return shellName;
+    }
+    return null;
+}
+/**
+ * Get history file path for a given shell
+ */
+function getHistoryPath(shell) {
+    const home = homedir();
+    if (!home)
+        return null;
+    const paths = HISTORY_PATHS[shell];
+    if (!paths)
+        return null;
+    return join(home, paths[0]);
+}
+/**
+ * Read last N lines from a file efficiently
+ * Uses tail-like approach: seek to end minus ~4KB, read, take last N lines
+ */
+function readLastLines(filePath, numLines) {
+    try {
+        // Read entire file - for most history files this is fine
+        // For very large files, we'd use a streaming approach
+        const content = readFileSync(filePath, 'utf-8');
+        const lines = content.split('\n');
+        // Filter out empty lines and get last N
+        const nonEmptyLines = lines.filter((line) => line.trim().length > 0);
+        return nonEmptyLines.slice(-numLines);
+    }
+    catch {
+        // File doesn't exist or can't be read
+        return [];
+    }
+}
+/**
+ * Get shell history
+ * Returns last N commands based on detected shell
+ *
+ * - bash: ~/.bash_history
+ * - zsh: ~/.zsh_history
+ * - fish: ~/.local/share/fish/fish_history (read raw lines)
+ * - other: empty array
+ *
+ * On error or unsupported shell, returns empty array (non-fatal)
+ */
+export function getShellHistory(maxHistory) {
+    const shell = detectShell();
+    if (!shell) {
+        return [];
+    }
+    const historyPath = getHistoryPath(shell);
+    if (!historyPath) {
+        return [];
+    }
+    const lines = readLastLines(historyPath, maxHistory);
+    // For fish shell, we read raw lines (matching Rust behavior)
+    // Fish uses format: "- cmd: <command>" but we return raw lines
+    // This matches the PRD: "The Rust code does NOT parse fish's - cmd: ... format"
+    return lines;
+}
+/**
+ * Get detected shell name (for testing/debugging)
+ */
+export function getDetectedShell() {
+    return detectShell();
+}

package/dist/context/index.d.ts

@@ -0,0 +1,24 @@
+import { Config } from '../config/types.js';
+import { ContextData } from './types.js';
+export { ContextError } from './types.js';
+export type { ContextData, SystemInfo } from './types.js';
+export { getSystemInfo, clearSystemCache } from './system.js';
+export { getCwd, scanDirectory, getRedactedCwd } from './directory.js';
+export { getShellHistory, getDetectedShell } from './history.js';
+export { readStdin, hasPipedStdin } from './stdin.js';
+export { redactPath, redactUsername, redactEnvVars } from './redaction.js';
+/**
+ * Gather all context information for the AI prompt
+ *
+ * Components:
+ * - System info (cached): OS, shell, user, memory
+ * - Current working directory (fatal if fails)
+ * - Directory files (sorted, truncated, redacted)
+ * - Shell history (last N commands)
+ * - Stdin content (only if piped, max 10KB)
+ *
+ * @param config - Runtime configuration with context settings
+ * @returns ContextData with all gathered information
+ * @throws ContextError if CWD cannot be determined (fatal)
+ */
+export declare function gatherContext(config: Config): Promise<ContextData>;

package/dist/context/index.js

@@ -0,0 +1,61 @@
+// Context gathering module - main entry point
+// Gathers system info, directory context, shell history, and stdin
+import { ContextError } from './types.js';
+import { getSystemInfo } from './system.js';
+import { getCwd, scanDirectory } from './directory.js';
+import { getShellHistory } from './history.js';
+import { readStdin } from './stdin.js';
+import { redactPath } from './redaction.js';
+// Re-export types and functions
+export { ContextError } from './types.js';
+export { getSystemInfo, clearSystemCache } from './system.js';
+export { getCwd, scanDirectory, getRedactedCwd } from './directory.js';
+export { getShellHistory, getDetectedShell } from './history.js';
+export { readStdin, hasPipedStdin } from './stdin.js';
+export { redactPath, redactUsername, redactEnvVars } from './redaction.js';
+/**
+ * Gather all context information for the AI prompt
+ *
+ * Components:
+ * - System info (cached): OS, shell, user, memory
+ * - Current working directory (fatal if fails)
+ * - Directory files (sorted, truncated, redacted)
+ * - Shell history (last N commands)
+ * - Stdin content (only if piped, max 10KB)
+ *
+ * @param config - Runtime configuration with context settings
+ * @returns ContextData with all gathered information
+ * @throws ContextError if CWD cannot be determined (fatal)
+ */
+export async function gatherContext(config) {
+    const { maxFiles, maxHistory, redactPaths, redactUsername } = config.context;
+    // 1. System info (cached, non-fatal)
+    const system = getSystemInfo(redactUsername);
+    // 2. CWD (fatal if fails)
+    let cwd;
+    try {
+        cwd = getCwd();
+        if (redactPaths) {
+            cwd = redactPath(cwd);
+        }
+    }
+    catch (err) {
+        if (err instanceof ContextError) {
+            throw err;
+        }
+        throw new ContextError(`Failed to gather context: ${err instanceof Error ? err.message : String(err)}`, 1);
+    }
+    // 3. Directory files (non-fatal, empty on error)
+    const files = scanDirectory(maxFiles, redactPaths);
+    // 4. Shell history (non-fatal, empty on error)
+    const history = getShellHistory(maxHistory);
+    // 5. Stdin (only if piped, non-fatal)
+    const stdin = await readStdin();
+    return {
+        system,
+        cwd,
+        files,
+        history,
+        stdin,
+    };
+}

package/dist/context/redaction.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Redact sensitive path information from a string
+ * Replaces home directory patterns with [REDACTED]
+ */
+export declare function redactPath(path: string): string;
+/**
+ * Redact username
+ */
+export declare function redactUsername(_username: string): string;
+/**
+ * Redact environment variables in a string
+ * Replaces $VAR and ${VAR} patterns
+ */
+export declare function redactEnvVars(text: string, envVars: string[]): string;

package/dist/context/redaction.js

@@ -0,0 +1,57 @@
+// Path and username redaction helpers for privacy
+import { homedir } from 'os';
+const REDACTED = '[REDACTED]';
+/**
+ * Redact sensitive path information from a string
+ * Replaces home directory patterns with [REDACTED]
+ */
+export function redactPath(path) {
+    const home = homedir();
+    if (!home)
+        return path;
+    // Normalize path separators for Windows
+    const normalizedPath = path.replace(/\\/g, '/');
+    const normalizedHome = home.replace(/\\/g, '/');
+    // Extract username from home path (e.g., /home/username or /Users/username)
+    const homeParts = normalizedHome.split('/');
+    const username = homeParts[homeParts.length - 1] || '';
+    let redacted = normalizedPath;
+    // Replace full home directory path
+    if (normalizedHome) {
+        const escapedHome = normalizedHome.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        redacted = redacted.replace(new RegExp(escapedHome, 'g'), REDACTED);
+    }
+    // Replace ~ (home shorthand)
+    redacted = redacted.replace(/^~\//, `${REDACTED}/`);
+    redacted = redacted.replace(/^~$/, REDACTED);
+    // Replace /home/username/ pattern
+    if (username) {
+        redacted = redacted.replace(new RegExp(`/home/${username}/`, 'g'), `${REDACTED}/`);
+        redacted = redacted.replace(new RegExp(`/Users/${username}/`, 'g'), `${REDACTED}/`);
+    }
+    // Restore original path separators for Windows
+    if (process.platform === 'win32') {
+        redacted = redacted.replace(/\//g, '\\');
+    }
+    return redacted;
+}
+/**
+ * Redact username
+ */
+export function redactUsername(_username) {
+    return REDACTED;
+}
+/**
+ * Redact environment variables in a string
+ * Replaces $VAR and ${VAR} patterns
+ */
+export function redactEnvVars(text, envVars) {
+    let redacted = text;
+    for (const envVar of envVars) {
+        // Replace ${VAR} pattern
+        redacted = redacted.replace(new RegExp(`\\$\\{${envVar}\\}`, 'g'), REDACTED);
+        // Replace $VAR pattern (word boundary)
+        redacted = redacted.replace(new RegExp(`\\$${envVar}\\b`, 'g'), REDACTED);
+    }
+    return redacted;
+}

package/dist/context/stdin.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Read stdin if it's not a TTY (i.e., data is being piped)
+ * Returns up to 10KB of content as UTF-8 string
+ * Returns undefined if stdin is a TTY or empty
+ *
+ * UTF-8 invalid sequences are replaced with replacement character (lossy decode)
+ */
+export declare function readStdin(): Promise<string | undefined>;
+/**
+ * Check if stdin has piped data available
+ * This is synchronous - useful for checking without reading
+ */
+export declare function hasPipedStdin(): boolean;

package/dist/context/stdin.js

@@ -0,0 +1,86 @@
+// Stdin input gathering for piped content
+const MAX_STDIN_BYTES = 10 * 1024; // 10 KB
+/**
+ * Read stdin if it's not a TTY (i.e., data is being piped)
+ * Returns up to 10KB of content as UTF-8 string
+ * Returns undefined if stdin is a TTY or empty
+ *
+ * UTF-8 invalid sequences are replaced with replacement character (lossy decode)
+ */
+export async function readStdin() {
+    // Check if stdin is a TTY
+    if (process.stdin.isTTY) {
+        return undefined;
+    }
+    // Check if stdin is readable (has data or will have data)
+    // In test environments, stdin might not be a TTY but also not have any data
+    if (!process.stdin.readable) {
+        return undefined;
+    }
+    // Check if stdin is already at EOF
+    if (process.stdin.readableEnded) {
+        return undefined;
+    }
+    const chunks = [];
+    let totalBytes = 0;
+    let hasReceivedData = false;
+    let endReceived = false;
+    return new Promise((resolve) => {
+        // Set a timeout to prevent hanging if no data comes
+        const timeout = setTimeout(() => {
+            if (!hasReceivedData) {
+                // No data received within timeout, assume empty stdin
+                cleanup();
+                resolve(undefined);
+            }
+        }, 100);
+        function cleanup() {
+            clearTimeout(timeout);
+            process.stdin.removeAllListeners('data');
+            process.stdin.removeAllListeners('end');
+            process.stdin.removeAllListeners('error');
+        }
+        process.stdin.on('data', (chunk) => {
+            hasReceivedData = true;
+            const remainingBytes = MAX_STDIN_BYTES - totalBytes;
+            if (remainingBytes <= 0) {
+                // We've already reached the limit, ignore further data
+                return;
+            }
+            // Only take what we need up to the limit
+            const bytesToTake = Math.min(chunk.length, remainingBytes);
+            chunks.push(chunk.subarray(0, bytesToTake));
+            totalBytes += bytesToTake;
+        });
+        process.stdin.on('end', () => {
+            if (endReceived)
+                return;
+            endReceived = true;
+            cleanup();
+            if (chunks.length === 0) {
+                resolve(undefined);
+                return;
+            }
+            const buffer = Buffer.concat(chunks);
+            // Convert to UTF-8 with lossy replacement for invalid sequences
+            const content = buffer.toString('utf8');
+            resolve(content.length > 0 ? content : undefined);
+        });
+        process.stdin.on('error', () => {
+            cleanup();
+            // Non-fatal: return undefined on error
+            resolve(undefined);
+        });
+        // Resume stdin if paused
+        if (process.stdin.isPaused()) {
+            process.stdin.resume();
+        }
+    });
+}
+/**
+ * Check if stdin has piped data available
+ * This is synchronous - useful for checking without reading
+ */
+export function hasPipedStdin() {
+    return !process.stdin.isTTY && process.stdin.readable;
+}

package/dist/context/system.d.ts

@@ -0,0 +1,11 @@
+import { SystemInfo } from './types.js';
+/**
+ * Get system information
+ * Results are cached for the process lifetime
+ * @param redactUser - Whether to redact the username
+ */
+export declare function getSystemInfo(redactUser?: boolean): SystemInfo;
+/**
+ * Clear the system info cache (useful for testing)
+ */
+export declare function clearSystemCache(): void;

package/dist/context/system.js

@@ -0,0 +1,56 @@
+// System information gathering - cached per process
+import { type, release, totalmem } from 'os';
+import { redactUsername } from './redaction.js';
+// Cached system info to avoid repeated OS calls
+let cachedSystemInfo = null;
+let cachedWithRedaction = false;
+/**
+ * Get shell name from SHELL environment variable
+ * Returns basename (e.g., '/bin/bash' -> 'bash')
+ */
+function getShell() {
+    const shell = process.env.SHELL || '';
+    if (!shell)
+        return 'unknown';
+    // Extract basename from path
+    const parts = shell.split('/');
+    return parts[parts.length - 1] || 'unknown';
+}
+/**
+ * Get username from environment variables
+ */
+function getUsername() {
+    return process.env.USER || process.env.USERNAME || 'unknown';
+}
+/**
+ * Get system information
+ * Results are cached for the process lifetime
+ * @param redactUser - Whether to redact the username
+ */
+export function getSystemInfo(redactUser = false) {
+    // Return cached value if available and redaction matches
+    if (cachedSystemInfo && cachedWithRedaction === redactUser) {
+        return cachedSystemInfo;
+    }
+    const rawUsername = getUsername();
+    const user = redactUser ? redactUsername(rawUsername) : rawUsername;
+    const info = {
+        osName: type(),
+        osVersion: release(),
+        architecture: process.arch,
+        shell: getShell(),
+        user,
+        totalMemoryMb: Math.floor(totalmem() / (1024 * 1024)),
+    };
+    // Cache the result
+    cachedSystemInfo = info;
+    cachedWithRedaction = redactUser;
+    return info;
+}
+/**
+ * Clear the system info cache (useful for testing)
+ */
+export function clearSystemCache() {
+    cachedSystemInfo = null;
+    cachedWithRedaction = false;
+}

package/dist/context/types.d.ts

@@ -0,0 +1,31 @@
+import { ClaiError } from '../error/index.js';
+export interface SystemInfo {
+    /** Operating system name (e.g., 'Linux', 'Darwin', 'Windows_NT') */
+    osName: string;
+    /** OS version string */
+    osVersion: string;
+    /** CPU architecture (e.g., 'x64', 'arm64') */
+    architecture: string;
+    /** Shell name (e.g., 'bash', 'zsh', 'fish') */
+    shell: string;
+    /** Username (may be redacted) */
+    user: string;
+    /** Total system memory in MB */
+    totalMemoryMb: number;
+}
+export interface ContextData {
+    /** System information */
+    system: SystemInfo;
+    /** Current working directory (may be redacted) */
+    cwd: string;
+    /** List of files in current directory (sorted, truncated, redacted) */
+    files: string[];
+    /** Recent shell history entries */
+    history: string[];
+    /** Piped stdin content (only when stdin is not a TTY) */
+    stdin?: string;
+}
+/** Error class for context gathering failures */
+export declare class ContextError extends ClaiError {
+    constructor(message: string, code?: number);
+}