magi-ai 0.1.0

package/dist/src/utils/file-validator.js

@@ -0,0 +1,124 @@
+/**
+ * File validator — shared by CLI, REPL, and MCP for input file validation.
+ *
+ * Extracted from slash-commands.ts validateWorkspaceFile() to provide
+ * a unified, structured result interface usable across all entry points.
+ */
+import { lstat, realpath, open } from 'node:fs/promises';
+import { dirname, resolve, relative } from 'node:path';
+import { isBinaryExtension } from './language-detector.js';
+// ── Public API ────────────────────────────────────────────────
+/**
+ * Validate a file path for safe access.
+ *
+ * Checks (in order):
+ * 1. Null bytes / empty path
+ * 2. Path traversal (relative path escapes basedir)
+ * 3. Realpath traversal (symlink parent escape)
+ * 4. Symlink target
+ * 5. Regular file check
+ * 6. Size limit
+ * 7. Binary extension check
+ * 8. Binary null-byte check (fallback)
+ */
+export async function validateFile(inputPath, options) {
+    // ── 1. Basic path validation ──
+    if (!inputPath || typeof inputPath !== 'string') {
+        return fail('INVALID_PATH', 'Invalid file path.');
+    }
+    if (inputPath.includes('\0')) {
+        return fail('INVALID_PATH', 'File path contains null bytes.');
+    }
+    const basedir = options?.basedir ?? process.cwd();
+    const absolutePath = resolve(basedir, inputPath);
+    const relativePath = relative(basedir, absolutePath);
+    // ── 2. Path traversal check ──
+    if (relativePath.startsWith('..') || resolve(relativePath) === relativePath) {
+        return fail('PATH_TRAVERSAL', 'Path traversal denied.');
+    }
+    // ── 3. Realpath traversal check ──
+    try {
+        const [realBase, realParent] = await Promise.all([
+            realpath(basedir),
+            realpath(dirname(absolutePath)),
+        ]);
+        if (!realParent.startsWith(`${realBase}/`) && realParent !== realBase) {
+            return fail('PATH_TRAVERSAL', 'Path traversal denied (symlink escape).');
+        }
+    }
+    catch (error) {
+        return mapErrnoError(error, inputPath);
+    }
+    // ── 4-6. Stat checks ──
+    let fileStats;
+    try {
+        fileStats = await lstat(absolutePath);
+    }
+    catch (error) {
+        return mapErrnoError(error, inputPath);
+    }
+    if (fileStats.isSymbolicLink()) {
+        return fail('SYMLINK', 'Symlink targets are not allowed.');
+    }
+    if (!fileStats.isFile()) {
+        return fail('NOT_FILE', `Not a regular file: ${inputPath}`);
+    }
+    if (options?.maxBytes !== undefined && fileStats.size > options.maxBytes) {
+        const sizeMB = (fileStats.size / 1024 / 1024).toFixed(1);
+        const limitKB = Math.round(options.maxBytes / 1024);
+        return fail('TOO_LARGE', `File too large: ${sizeMB} MB (max ${limitKB} KB).`);
+    }
+    // ── 7-8. Binary checks ──
+    if (options?.rejectBinary) {
+        if (isBinaryExtension(absolutePath)) {
+            return fail('BINARY', `Binary file detected (by extension): ${inputPath}`);
+        }
+        if (await containsNullBytes(absolutePath)) {
+            return fail('BINARY', `Binary file detected (null bytes): ${inputPath}`);
+        }
+    }
+    return {
+        ok: true,
+        file: {
+            absolutePath,
+            relativePath,
+            sizeBytes: fileStats.size,
+        },
+    };
+}
+/**
+ * Check if the first N bytes of a file contain null bytes.
+ * Returns true if null bytes are found (likely binary file).
+ */
+export async function containsNullBytes(filePath, checkBytes = 512) {
+    let fh;
+    try {
+        fh = await open(filePath, 'r');
+        const buf = Buffer.alloc(checkBytes);
+        const { bytesRead } = await fh.read(buf, 0, checkBytes, 0);
+        for (let i = 0; i < bytesRead; i++) {
+            if (buf[i] === 0)
+                return true;
+        }
+        return false;
+    }
+    catch {
+        // If we can't read, don't block — let the caller handle read errors
+        return false;
+    }
+    finally {
+        await fh?.close();
+    }
+}
+// ── Helpers ───────────────────────────────────────────────────
+function fail(code, message) {
+    return { ok: false, error: { code, message } };
+}
+function mapErrnoError(error, inputPath) {
+    const code = error.code;
+    if (code === 'ENOENT')
+        return fail('ENOENT', `File not found: ${inputPath}`);
+    if (code === 'EACCES')
+        return fail('EACCES', `Permission denied: ${inputPath}`);
+    return fail('ENOENT', `Cannot access: ${inputPath}`);
+}

package/dist/src/utils/fire-and-forget.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Execute a promise without awaiting, logging any errors at debug level.
+ * Prevents unhandled rejection warnings while keeping the error trail.
+ */
+export declare function fireAndForget(promise: Promise<unknown>, label: string): void;

package/dist/src/utils/fire-and-forget.js

@@ -0,0 +1,10 @@
+import { logger } from './logger.js';
+/**
+ * Execute a promise without awaiting, logging any errors at debug level.
+ * Prevents unhandled rejection warnings while keeping the error trail.
+ */
+export function fireAndForget(promise, label) {
+    promise.catch((err) => {
+        logger.debug(`[fire-and-forget:${label}] ${String(err)}`);
+    });
+}

package/dist/src/utils/flag-validator.d.ts

@@ -0,0 +1,21 @@
+/**
+ * CLI flag safety validation for MAGI system.
+ *
+ * Prevents unsafe flags (e.g. permission bypasses, sandbox disabling)
+ * from being passed to AI CLI tools, with tool-specific overrides
+ * where a flag is required for normal operation.
+ */
+import { MagiError } from './errors.js';
+export declare class UnsafeFlagError extends MagiError {
+    readonly flags: string[];
+    readonly tool: string;
+    constructor(flags: string[], tool: string);
+}
+/**
+ * Assert that no unsafe flags are present for the given tool.
+ *
+ * @param flags - The flags array to validate
+ * @param tool  - The CLI tool name (e.g. "claude", "codex", "gemini")
+ * @throws {UnsafeFlagError} if any unsafe flags are detected
+ */
+export declare function assertNoUnsafeFlags(flags: string[], tool: string): void;

package/dist/src/utils/flag-validator.js

@@ -0,0 +1,79 @@
+/**
+ * CLI flag safety validation for MAGI system.
+ *
+ * Prevents unsafe flags (e.g. permission bypasses, sandbox disabling)
+ * from being passed to AI CLI tools, with tool-specific overrides
+ * where a flag is required for normal operation.
+ */
+import { MagiError } from './errors.js';
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+export class UnsafeFlagError extends MagiError {
+    flags;
+    tool;
+    constructor(flags, tool) {
+        super(`Unsafe flags detected for ${tool}: ${flags.join(', ')}`, 'UNSAFE_FLAG');
+        this.flags = flags;
+        this.tool = tool;
+    }
+}
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Flags that bypass safety measures in AI CLIs. */
+const UNSAFE_FLAGS = [
+    '--dangerously-skip-permissions', // Claude
+    '--no-verify', // Various
+    '--approval-mode=full-auto', // Gemini (bypasses plan mode)
+    '--full-auto', // But codex MUST use full-auto, so context matters
+    '--yolo', // Codex unofficial
+    '--no-sandbox', // Codex
+    '--sandbox=off', // Codex
+];
+/**
+ * Flags that are always allowed despite looking unsafe.
+ * Codex requires --full-auto for non-interactive exec.
+ */
+const ALLOWED_OVERRIDES = {
+    codex: ['--full-auto'],
+};
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/**
+ * Assert that no unsafe flags are present for the given tool.
+ *
+ * @param flags - The flags array to validate
+ * @param tool  - The CLI tool name (e.g. "claude", "codex", "gemini")
+ * @throws {UnsafeFlagError} if any unsafe flags are detected
+ */
+export function assertNoUnsafeFlags(flags, tool) {
+    const overrides = ALLOWED_OVERRIDES[tool] ?? [];
+    const detected = [];
+    for (let i = 0; i < flags.length; i++) {
+        const flag = flags[i];
+        // Direct match (existing logic)
+        if (UNSAFE_FLAGS.includes(flag) &&
+            !overrides.includes(flag)) {
+            detected.push(flag);
+            continue;
+        }
+        // Split form: '--approval-mode=full-auto' → ['--approval-mode', 'full-auto']
+        for (const unsafe of UNSAFE_FLAGS) {
+            if (!unsafe.includes('='))
+                continue;
+            const eqIdx = unsafe.indexOf('=');
+            const name = unsafe.slice(0, eqIdx);
+            const value = unsafe.slice(eqIdx + 1);
+            if (flag === name && flags[i + 1] === value && !overrides.includes(unsafe)) {
+                detected.push(`${flag}=${flags[i + 1]}`);
+                i++;
+                break;
+            }
+        }
+    }
+    if (detected.length > 0) {
+        throw new UnsafeFlagError(detected, tool);
+    }
+}

package/dist/src/utils/freeze.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Deep freeze utility for immutable configuration objects.
+ *
+ * Recursively applies Object.freeze() to an object and all nested
+ * objects/arrays. Already-frozen objects are skipped to prevent
+ * infinite recursion with circular references.
+ */
+export declare function deepFreeze<T extends object>(obj: T): Readonly<T>;

package/dist/src/utils/freeze.js

@@ -0,0 +1,16 @@
+/**
+ * Deep freeze utility for immutable configuration objects.
+ *
+ * Recursively applies Object.freeze() to an object and all nested
+ * objects/arrays. Already-frozen objects are skipped to prevent
+ * infinite recursion with circular references.
+ */
+export function deepFreeze(obj) {
+    Object.freeze(obj);
+    for (const value of Object.values(obj)) {
+        if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+            deepFreeze(value);
+        }
+    }
+    return obj;
+}

package/dist/src/utils/language-detector.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Language detector — maps file extensions to programming language names.
+ *
+ * Used by file-validator, auto-collector, and CLI/REPL/MCP to set
+ * `artifact.language` automatically.
+ */
+/**
+ * Detect programming language from file path extension.
+ * Case-insensitive. Returns undefined for unknown extensions.
+ */
+export declare function detectLanguage(filePath: string): string | undefined;
+/**
+ * Check if a file extension indicates a binary file.
+ * Case-insensitive. Returns false for unknown extensions.
+ */
+export declare function isBinaryExtension(filePath: string): boolean;

package/dist/src/utils/language-detector.js

@@ -0,0 +1,159 @@
+/**
+ * Language detector — maps file extensions to programming language names.
+ *
+ * Used by file-validator, auto-collector, and CLI/REPL/MCP to set
+ * `artifact.language` automatically.
+ */
+/** Extension → language mapping (lowercase, without dot) */
+const EXTENSION_MAP = {
+    // JavaScript / TypeScript
+    js: 'javascript',
+    jsx: 'javascript',
+    mjs: 'javascript',
+    cjs: 'javascript',
+    ts: 'typescript',
+    tsx: 'typescript',
+    mts: 'typescript',
+    cts: 'typescript',
+    // Web
+    html: 'html',
+    htm: 'html',
+    css: 'css',
+    scss: 'scss',
+    sass: 'sass',
+    less: 'less',
+    svg: 'svg',
+    vue: 'vue',
+    svelte: 'svelte',
+    // Systems
+    c: 'c',
+    h: 'c',
+    cpp: 'cpp',
+    cxx: 'cpp',
+    cc: 'cpp',
+    hpp: 'cpp',
+    rs: 'rust',
+    go: 'go',
+    zig: 'zig',
+    // JVM
+    java: 'java',
+    kt: 'kotlin',
+    kts: 'kotlin',
+    scala: 'scala',
+    groovy: 'groovy',
+    // Scripting
+    py: 'python',
+    pyi: 'python',
+    rb: 'ruby',
+    php: 'php',
+    pl: 'perl',
+    pm: 'perl',
+    lua: 'lua',
+    r: 'r',
+    jl: 'julia',
+    // Shell
+    sh: 'shell',
+    bash: 'shell',
+    zsh: 'shell',
+    fish: 'shell',
+    ps1: 'powershell',
+    // Data / Config
+    json: 'json',
+    jsonc: 'json',
+    yaml: 'yaml',
+    yml: 'yaml',
+    toml: 'toml',
+    xml: 'xml',
+    csv: 'csv',
+    ini: 'ini',
+    env: 'dotenv',
+    // Markup / Docs
+    md: 'markdown',
+    mdx: 'markdown',
+    rst: 'restructuredtext',
+    tex: 'latex',
+    // DevOps
+    dockerfile: 'dockerfile',
+    tf: 'terraform',
+    hcl: 'hcl',
+    // Database
+    sql: 'sql',
+    graphql: 'graphql',
+    gql: 'graphql',
+    prisma: 'prisma',
+    // Mobile
+    swift: 'swift',
+    m: 'objective-c',
+    dart: 'dart',
+    // Other
+    proto: 'protobuf',
+    ex: 'elixir',
+    exs: 'elixir',
+    erl: 'erlang',
+    hs: 'haskell',
+    ml: 'ocaml',
+    fs: 'fsharp',
+    cs: 'csharp',
+    vb: 'vb',
+    clj: 'clojure',
+    lisp: 'lisp',
+    el: 'elisp',
+    vim: 'vim',
+    nix: 'nix',
+};
+/** Binary file extensions (not programming languages) */
+const BINARY_EXTENSIONS = new Set([
+    // Images
+    'png', 'jpg', 'jpeg', 'gif', 'bmp', 'ico', 'webp', 'tiff', 'tif', 'avif',
+    // Fonts
+    'woff', 'woff2', 'ttf', 'otf', 'eot',
+    // Archives
+    'zip', 'tar', 'gz', 'bz2', 'xz', 'rar', '7z', 'zst',
+    // Executables / Libraries
+    'exe', 'dll', 'so', 'dylib', 'a', 'lib', 'o', 'obj',
+    // Media
+    'mp3', 'mp4', 'wav', 'ogg', 'flac', 'avi', 'mkv', 'mov', 'webm',
+    // Documents
+    'pdf', 'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx',
+    // Binary data
+    'wasm', 'bin', 'dat', 'db', 'sqlite', 'sqlite3',
+    // Package
+    'jar', 'war', 'apk', 'ipa', 'dmg', 'iso', 'img',
+]);
+/**
+ * Detect programming language from file path extension.
+ * Case-insensitive. Returns undefined for unknown extensions.
+ */
+export function detectLanguage(filePath) {
+    const ext = extractExtension(filePath);
+    if (!ext)
+        return undefined;
+    return EXTENSION_MAP[ext];
+}
+/**
+ * Check if a file extension indicates a binary file.
+ * Case-insensitive. Returns false for unknown extensions.
+ */
+export function isBinaryExtension(filePath) {
+    const ext = extractExtension(filePath);
+    if (!ext)
+        return false;
+    return BINARY_EXTENSIONS.has(ext);
+}
+/** Extract lowercase extension from a file path (without dot). */
+function extractExtension(filePath) {
+    // Handle filenames like "Dockerfile" (no extension)
+    const basename = filePath.split(/[\\/]/).pop() ?? filePath;
+    const lowerBasename = basename.toLowerCase();
+    // Special filenames
+    if (lowerBasename === 'dockerfile' || lowerBasename.startsWith('dockerfile.')) {
+        return 'dockerfile';
+    }
+    if (lowerBasename === 'makefile' || lowerBasename === 'gnumakefile') {
+        return 'makefile'; // not in EXTENSION_MAP — returns undefined for detectLanguage
+    }
+    const dotIdx = basename.lastIndexOf('.');
+    if (dotIdx === -1 || dotIdx === basename.length - 1)
+        return undefined;
+    return basename.slice(dotIdx + 1).toLowerCase();
+}

package/dist/src/utils/latency-tracker.d.ts

@@ -0,0 +1,45 @@
+import type { MagiUnit } from '../types/core.js';
+interface LatencyStats {
+    count: number;
+    p50: number;
+    p90: number;
+    p99: number;
+    mean: number;
+    min: number;
+    max: number;
+}
+/**
+ * Tracks adapter latency and provides dynamic timeout recommendations.
+ *
+ * Uses P90-based dynamic timeouts with a margin multiplier and sliding window.
+ * Only successful executions are counted for timeout calculation.
+ */
+export declare class LatencyTracker {
+    private readonly windowSize;
+    private readonly marginMultiplier;
+    private readonly minTimeoutMs;
+    private readonly maxTimeoutMs;
+    private records;
+    constructor(windowSize?: number, marginMultiplier?: number, minTimeoutMs?: number, maxTimeoutMs?: number);
+    /**
+     * Record a latency observation.
+     */
+    record(unit: MagiUnit, durationMs: number, success: boolean): void;
+    /**
+     * Get a recommended timeout for a given unit.
+     * Returns P90 * marginMultiplier, clamped to [minTimeoutMs, maxTimeoutMs].
+     * Falls back to fallbackMs when there are insufficient samples.
+     */
+    getTimeout(unit: MagiUnit, fallbackMs: number): number;
+    /**
+     * Get latency statistics for a given unit.
+     * Returns null if no records exist.
+     */
+    getStats(unit: MagiUnit): LatencyStats | null;
+    /**
+     * Clear all records, or records for a specific unit.
+     */
+    clear(unit?: MagiUnit): void;
+    private percentile;
+}
+export {};

package/dist/src/utils/latency-tracker.js

@@ -0,0 +1,100 @@
+/**
+ * Tracks adapter latency and provides dynamic timeout recommendations.
+ *
+ * Uses P90-based dynamic timeouts with a margin multiplier and sliding window.
+ * Only successful executions are counted for timeout calculation.
+ */
+export class LatencyTracker {
+    windowSize;
+    marginMultiplier;
+    minTimeoutMs;
+    maxTimeoutMs;
+    records = [];
+    constructor(windowSize = 20, marginMultiplier = 1.5, minTimeoutMs = 10_000, maxTimeoutMs = 600_000) {
+        this.windowSize = windowSize;
+        this.marginMultiplier = marginMultiplier;
+        this.minTimeoutMs = minTimeoutMs;
+        this.maxTimeoutMs = maxTimeoutMs;
+    }
+    /**
+     * Record a latency observation.
+     */
+    record(unit, durationMs, success) {
+        this.records.push({
+            unit,
+            durationMs,
+            success,
+            recordedAt: Date.now(),
+        });
+        // Evict oldest records beyond window size (per unit)
+        const unitRecords = this.records.filter(r => r.unit === unit);
+        if (unitRecords.length > this.windowSize) {
+            // Find the oldest record for this unit and remove it
+            const oldestIndex = this.records.findIndex(r => r.unit === unit);
+            if (oldestIndex !== -1) {
+                this.records.splice(oldestIndex, 1);
+            }
+        }
+    }
+    /**
+     * Get a recommended timeout for a given unit.
+     * Returns P90 * marginMultiplier, clamped to [minTimeoutMs, maxTimeoutMs].
+     * Falls back to fallbackMs when there are insufficient samples.
+     */
+    getTimeout(unit, fallbackMs) {
+        const successRecords = this.records
+            .filter(r => r.unit === unit && r.success)
+            .map(r => r.durationMs)
+            .sort((a, b) => a - b);
+        // Need at least 3 successful samples to calculate P90
+        if (successRecords.length < 3) {
+            return fallbackMs;
+        }
+        const p90 = this.percentile(successRecords, 0.90);
+        const recommended = Math.round(p90 * this.marginMultiplier);
+        return Math.max(this.minTimeoutMs, Math.min(this.maxTimeoutMs, recommended));
+    }
+    /**
+     * Get latency statistics for a given unit.
+     * Returns null if no records exist.
+     */
+    getStats(unit) {
+        const durations = this.records
+            .filter(r => r.unit === unit && r.success)
+            .map(r => r.durationMs)
+            .sort((a, b) => a - b);
+        if (durations.length === 0)
+            return null;
+        return {
+            count: durations.length,
+            p50: this.percentile(durations, 0.50),
+            p90: this.percentile(durations, 0.90),
+            p99: this.percentile(durations, 0.99),
+            mean: durations.reduce((sum, d) => sum + d, 0) / durations.length,
+            min: durations[0],
+            max: durations[durations.length - 1],
+        };
+    }
+    /**
+     * Clear all records, or records for a specific unit.
+     */
+    clear(unit) {
+        if (unit) {
+            this.records = this.records.filter(r => r.unit !== unit);
+        }
+        else {
+            this.records = [];
+        }
+    }
+    percentile(sorted, p) {
+        if (sorted.length === 0)
+            return 0;
+        if (sorted.length === 1)
+            return sorted[0];
+        const index = p * (sorted.length - 1);
+        const lower = Math.floor(index);
+        const upper = Math.ceil(index);
+        const weight = index - lower;
+        return sorted[lower] * (1 - weight) + sorted[upper] * weight;
+    }
+}

package/dist/src/utils/logger.d.ts

@@ -0,0 +1,33 @@
+import type { AuditEvent, AuditLogConfig } from '../audit/types.js';
+import { AuditLogWriter } from '../audit/writer.js';
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Suppress console output during TUI mode.
+ * Logs are buffered and flushed when TUI mode is disabled.
+ */
+export declare function setTuiMode(enabled: boolean): void;
+export declare function setLogLevel(level: LogLevel): void;
+/**
+ * Initialize audit logging. Must be called before logger.audit() will write entries.
+ * If not called, audit() calls are silently ignored.
+ */
+export declare function initAuditLog(config: AuditLogConfig): Promise<void>;
+/**
+ * Get the current audit writer (for testing purposes).
+ */
+export declare function getAuditWriter(): AuditLogWriter | null;
+/**
+ * Reset audit writer (for testing teardown).
+ */
+export declare function resetAuditWriter(): void;
+export declare const logger: {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Write an audit log entry. Fire-and-forget -- never blocks the caller.
+     * If audit logging is not initialized, the call is silently ignored.
+     */
+    audit(event: AuditEvent, deliberationId: string, data: Record<string, unknown>): void;
+};