@build-astron-co/nimbus 0.2.0 → 0.4.0

package/dist/src/history/index.js

@@ -0,0 +1,6 @@
+/**
+ * History Module
+ *
+ * Exports history management functionality
+ */
+export { HistoryManager, historyManager } from './manager';

package/dist/src/history/manager.js

@@ -0,0 +1,199 @@
+/**
+ * History Manager
+ *
+ * Manages command history persistence at ~/.nimbus/history.json
+ * with remote sync to the State Service for cross-session persistence.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+const HISTORY_FILE_VERSION = 1;
+const MAX_HISTORY_ENTRIES = 1000;
+/**
+ * Generate a unique ID for history entries
+ */
+function generateId() {
+    return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+/**
+ * Create an empty history file structure
+ */
+function createEmptyHistoryFile() {
+    const now = new Date().toISOString();
+    return {
+        version: HISTORY_FILE_VERSION,
+        entries: [],
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+/**
+ * HistoryManager class for command history persistence
+ * with optional remote sync to State Service.
+ */
+export class HistoryManager {
+    historyPath;
+    historyFile = null;
+    constructor(historyPath) {
+        this.historyPath = historyPath || path.join(os.homedir(), '.nimbus', 'history.json');
+    }
+    /**
+     * Get the path to the history file
+     */
+    getHistoryPath() {
+        return this.historyPath;
+    }
+    /**
+     * Ensure the history directory exists
+     */
+    ensureDirectory() {
+        const dir = path.dirname(this.historyPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+    }
+    /**
+     * Load history file from disk, creating if necessary
+     */
+    load() {
+        if (this.historyFile) {
+            return this.historyFile;
+        }
+        this.ensureDirectory();
+        if (!fs.existsSync(this.historyPath)) {
+            this.historyFile = createEmptyHistoryFile();
+            return this.historyFile;
+        }
+        try {
+            const content = fs.readFileSync(this.historyPath, 'utf-8');
+            const parsed = JSON.parse(content);
+            // Validate version and migrate if needed
+            if (parsed.version !== HISTORY_FILE_VERSION) {
+                parsed.version = HISTORY_FILE_VERSION;
+            }
+            // Ensure required fields exist
+            parsed.entries = parsed.entries || [];
+            this.historyFile = parsed;
+            return this.historyFile;
+        }
+        catch {
+            // If file is corrupted, start fresh
+            this.historyFile = createEmptyHistoryFile();
+            return this.historyFile;
+        }
+    }
+    /**
+     * Save history file to disk
+     */
+    save(historyFile) {
+        this.ensureDirectory();
+        const fileToSave = historyFile || this.historyFile;
+        if (!fileToSave) {
+            throw new Error('No history file to save');
+        }
+        fileToSave.updatedAt = new Date().toISOString();
+        this.historyFile = fileToSave;
+        const content = JSON.stringify(fileToSave, null, 2);
+        fs.writeFileSync(this.historyPath, content, { mode: 0o600 });
+    }
+    /**
+     * Add a new entry to history
+     */
+    addEntry(command, args, metadata) {
+        const historyFile = this.load();
+        const entry = {
+            id: generateId(),
+            command,
+            args,
+            timestamp: new Date().toISOString(),
+            status: 'pending',
+            metadata,
+        };
+        historyFile.entries.unshift(entry);
+        // Trim to max entries
+        if (historyFile.entries.length > MAX_HISTORY_ENTRIES) {
+            historyFile.entries = historyFile.entries.slice(0, MAX_HISTORY_ENTRIES);
+        }
+        this.save(historyFile);
+        return entry;
+    }
+    /**
+     * Update an existing entry
+     */
+    updateEntry(id, updates) {
+        const historyFile = this.load();
+        const entryIndex = historyFile.entries.findIndex(e => e.id === id);
+        if (entryIndex === -1) {
+            return null;
+        }
+        historyFile.entries[entryIndex] = {
+            ...historyFile.entries[entryIndex],
+            ...updates,
+        };
+        this.save(historyFile);
+        return historyFile.entries[entryIndex];
+    }
+    /**
+     * Complete an entry with success or failure
+     */
+    completeEntry(id, status, duration, result) {
+        return this.updateEntry(id, { status, duration, result });
+    }
+    /**
+     * Get history entries with optional filtering.
+     * Reads from local file storage.
+     */
+    async getEntries(options = {}) {
+        // Read from local file
+        const historyFile = this.load();
+        let entries = [...historyFile.entries];
+        // Filter by command
+        if (options.command) {
+            entries = entries.filter(e => e.command.toLowerCase().includes(options.command.toLowerCase()));
+        }
+        // Filter by status
+        if (options.status) {
+            entries = entries.filter(e => e.status === options.status);
+        }
+        // Filter by since date
+        if (options.since) {
+            const sinceDate = new Date(options.since);
+            entries = entries.filter(e => new Date(e.timestamp) >= sinceDate);
+        }
+        // Filter by until date
+        if (options.until) {
+            const untilDate = new Date(options.until);
+            entries = entries.filter(e => new Date(e.timestamp) <= untilDate);
+        }
+        // Apply limit
+        if (options.limit && options.limit > 0) {
+            entries = entries.slice(0, options.limit);
+        }
+        return entries;
+    }
+    /**
+     * Get a single entry by ID
+     */
+    getEntry(id) {
+        const historyFile = this.load();
+        return historyFile.entries.find(e => e.id === id) || null;
+    }
+    /**
+     * Clear all history
+     */
+    clear() {
+        this.historyFile = createEmptyHistoryFile();
+        this.save();
+    }
+    /**
+     * Reload history file from disk
+     */
+    reload() {
+        this.historyFile = null;
+        return this.load();
+    }
+}
+/**
+ * Singleton instance for global access
+ */
+export const historyManager = new HistoryManager();

package/dist/src/history/types.js

@@ -0,0 +1,6 @@
+/**
+ * History Types
+ *
+ * Type definitions for command history tracking
+ */
+export {};

package/dist/src/hooks/config.js

@@ -0,0 +1,318 @@
+/**
+ * Hooks Configuration
+ *
+ * Parses and validates `.nimbus/hooks.yaml` configuration files.
+ * Provides types and utilities for the Nimbus hooks system that allows
+ * users to run custom scripts before/after tool invocations.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/** All valid hook event names for validation */
+const VALID_HOOK_EVENTS = [
+    'PreToolUse',
+    'PostToolUse',
+    'PermissionRequest',
+];
+/** Default timeout in milliseconds for hook execution */
+export const DEFAULT_HOOK_TIMEOUT = 30_000;
+/**
+ * Parse raw YAML text into an array of meaningful lines with indentation info.
+ * Strips comments and blank lines.
+ *
+ * @param text - Raw YAML content
+ * @returns Array of parsed lines with indentation levels
+ */
+function tokenizeYaml(text) {
+    const lines = [];
+    for (const raw of text.split('\n')) {
+        // Strip inline comments (but not inside quoted strings)
+        const withoutComment = raw.replace(/#.*$/, '');
+        const trimmed = withoutComment.trimEnd();
+        if (trimmed.length === 0) {
+            continue;
+        }
+        const indent = trimmed.search(/\S/);
+        if (indent === -1) {
+            continue;
+        }
+        lines.push({ indent, content: trimmed.trim() });
+    }
+    return lines;
+}
+/**
+ * Remove surrounding quotes (single or double) from a string value.
+ *
+ * @param value - Potentially quoted string
+ * @returns Unquoted string
+ */
+function unquote(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/**
+ * Coerce a raw YAML string value to the appropriate JS primitive.
+ *
+ * @param raw - Raw string value from YAML
+ * @returns Coerced value (string, number, boolean, or null)
+ */
+function coerceValue(raw) {
+    if (raw === 'true') {
+        return true;
+    }
+    if (raw === 'false') {
+        return false;
+    }
+    if (raw === 'null' || raw === '~') {
+        return null;
+    }
+    const unquoted = unquote(raw);
+    if (unquoted !== raw) {
+        // Was quoted -- keep as string
+        return unquoted;
+    }
+    // Try number coercion
+    if (raw !== '' && !isNaN(Number(raw))) {
+        return Number(raw);
+    }
+    return raw;
+}
+/**
+ * Minimal recursive-descent YAML parser.
+ *
+ * Handles the subset of YAML needed for hooks configuration:
+ * - Top-level maps
+ * - Arrays of objects (using `- key: value` syntax)
+ * - Scalar values (string, number, boolean)
+ * - Nested maps
+ *
+ * This is intentionally NOT a full YAML parser. It covers the structure
+ * required by `.nimbus/hooks.yaml` without requiring an external dependency.
+ *
+ * @param text - Raw YAML content
+ * @returns Parsed object
+ */
+function parseYaml(text) {
+    const lines = tokenizeYaml(text);
+    let pos = 0;
+    /**
+     * Parse a mapping (object) at the given indentation level.
+     */
+    function parseMapping(minIndent) {
+        const result = {};
+        while (pos < lines.length) {
+            const line = lines[pos];
+            // If the line is at a lower indent, we've left this mapping
+            if (line.indent < minIndent) {
+                break;
+            }
+            // Skip lines that are deeper than expected (shouldn't happen in
+            // well-formed input, but be defensive)
+            if (line.indent > minIndent && !line.content.startsWith('- ')) {
+                pos++;
+                continue;
+            }
+            // Array items are handled by the caller (parseArray)
+            if (line.content.startsWith('- ')) {
+                break;
+            }
+            const colonIdx = line.content.indexOf(':');
+            if (colonIdx === -1) {
+                pos++;
+                continue;
+            }
+            const key = line.content.slice(0, colonIdx).trim();
+            const rest = line.content.slice(colonIdx + 1).trim();
+            pos++;
+            if (rest.length > 0) {
+                // Inline scalar value: `key: value`
+                result[key] = coerceValue(rest);
+            }
+            else {
+                // Value is on subsequent indented lines -- either a nested map or array
+                if (pos < lines.length && lines[pos].indent > minIndent) {
+                    const childIndent = lines[pos].indent;
+                    if (lines[pos].content.startsWith('- ')) {
+                        result[key] = parseArray(childIndent);
+                    }
+                    else {
+                        result[key] = parseMapping(childIndent);
+                    }
+                }
+                else {
+                    // Empty value
+                    result[key] = null;
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Parse an array at the given indentation level.
+     * Each array element starts with `- ` and can contain inline key-value
+     * pairs or a nested block mapping.
+     */
+    function parseArray(minIndent) {
+        const result = [];
+        while (pos < lines.length) {
+            const line = lines[pos];
+            if (line.indent < minIndent) {
+                break;
+            }
+            if (!line.content.startsWith('- ')) {
+                break;
+            }
+            // Strip the leading `- `
+            const afterDash = line.content.slice(2).trim();
+            pos++;
+            if (afterDash.includes(':')) {
+                // Inline object start: `- key: value`
+                const obj = {};
+                const colonIdx = afterDash.indexOf(':');
+                const key = afterDash.slice(0, colonIdx).trim();
+                const val = afterDash.slice(colonIdx + 1).trim();
+                obj[key] = val.length > 0 ? coerceValue(val) : null;
+                // Collect subsequent indented key-value pairs belonging to the same item
+                while (pos < lines.length) {
+                    const next = lines[pos];
+                    // Must be indented deeper than the `- ` marker and NOT be another array item
+                    if (next.indent <= minIndent || next.content.startsWith('- ')) {
+                        break;
+                    }
+                    const nextColon = next.content.indexOf(':');
+                    if (nextColon === -1) {
+                        pos++;
+                        continue;
+                    }
+                    const nk = next.content.slice(0, nextColon).trim();
+                    const nv = next.content.slice(nextColon + 1).trim();
+                    obj[nk] = nv.length > 0 ? coerceValue(nv) : null;
+                    pos++;
+                }
+                result.push(obj);
+            }
+            else if (afterDash.length > 0) {
+                // Scalar array element: `- value`
+                result.push(coerceValue(afterDash));
+            }
+            else {
+                // Block-style object under `- `
+                if (pos < lines.length && lines[pos].indent > minIndent) {
+                    const childIndent = lines[pos].indent;
+                    result.push(parseMapping(childIndent));
+                }
+            }
+        }
+        return result;
+    }
+    return parseMapping(0);
+}
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate a single hook definition and return any errors found.
+ *
+ * Checks:
+ * - `match` is a non-empty string that compiles as a valid RegExp
+ * - `command` is a non-empty string
+ * - `timeout`, if provided, is a positive number
+ *
+ * @param hook - The hook definition to validate
+ * @returns Array of human-readable error strings (empty if valid)
+ */
+export function validateHookDefinition(hook) {
+    const errors = [];
+    // match
+    if (typeof hook.match !== 'string' || hook.match.length === 0) {
+        errors.push('hook "match" must be a non-empty string');
+    }
+    else {
+        try {
+            new RegExp(hook.match);
+        }
+        catch {
+            errors.push(`hook "match" is not a valid regex: "${hook.match}"`);
+        }
+    }
+    // command
+    if (typeof hook.command !== 'string' || hook.command.length === 0) {
+        errors.push('hook "command" must be a non-empty string');
+    }
+    // timeout (optional)
+    if (hook.timeout !== undefined) {
+        if (typeof hook.timeout !== 'number' || hook.timeout <= 0) {
+            errors.push('hook "timeout" must be a positive number');
+        }
+    }
+    return errors;
+}
+// ---------------------------------------------------------------------------
+// Loader
+// ---------------------------------------------------------------------------
+/**
+ * Load and validate a hooks configuration from `<projectDir>/.nimbus/hooks.yaml`.
+ *
+ * @param projectDir - Absolute or relative path to the project root directory
+ * @returns Parsed and validated `HooksConfig`, or `null` if the file does not exist
+ * @throws Error if the file exists but contains invalid configuration
+ *
+ * @example
+ * ```ts
+ * const config = loadHooksConfig('/path/to/project');
+ * if (config) {
+ *   console.log(config.hooks.PreToolUse);
+ * }
+ * ```
+ */
+export function loadHooksConfig(projectDir) {
+    const configPath = path.join(projectDir, '.nimbus', 'hooks.yaml');
+    if (!fs.existsSync(configPath)) {
+        return null;
+    }
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    const parsed = parseYaml(raw);
+    // Validate top-level structure
+    if (!parsed.hooks || typeof parsed.hooks !== 'object') {
+        throw new Error(`Invalid hooks config at ${configPath}: missing top-level "hooks" key`);
+    }
+    const hooksRaw = parsed.hooks;
+    // Build the validated config, ensuring all three event types are present
+    const config = {
+        hooks: {
+            PreToolUse: [],
+            PostToolUse: [],
+            PermissionRequest: [],
+        },
+    };
+    for (const [eventName, definitions] of Object.entries(hooksRaw)) {
+        // Validate event name
+        if (!VALID_HOOK_EVENTS.includes(eventName)) {
+            throw new Error(`Invalid hooks config at ${configPath}: unknown hook event "${eventName}". ` +
+                `Valid events: ${VALID_HOOK_EVENTS.join(', ')}`);
+        }
+        const event = eventName;
+        if (!Array.isArray(definitions)) {
+            throw new Error(`Invalid hooks config at ${configPath}: "${eventName}" must be an array of hook definitions`);
+        }
+        for (let i = 0; i < definitions.length; i++) {
+            const def = definitions[i];
+            if (typeof def !== 'object' || def === null) {
+                throw new Error(`Invalid hooks config at ${configPath}: ${eventName}[${i}] must be an object`);
+            }
+            const hookDef = {
+                match: String(def.match ?? ''),
+                command: String(def.command ?? ''),
+                timeout: def.timeout !== undefined && def.timeout !== null ? Number(def.timeout) : undefined,
+            };
+            const validationErrors = validateHookDefinition(hookDef);
+            if (validationErrors.length > 0) {
+                throw new Error(`Invalid hooks config at ${configPath}: ${eventName}[${i}]: ${validationErrors.join('; ')}`);
+            }
+            config.hooks[event].push(hookDef);
+        }
+    }
+    return config;
+}