@build-astron-co/nimbus 0.3.0 → 0.4.0

package/dist/src/agent/deploy-preview.js

@@ -0,0 +1,395 @@
+/**
+ * Deploy Preview
+ *
+ * Generates dry-run previews for infrastructure changes with
+ * blast radius analysis. Shows what will be created, modified,
+ * or destroyed before the user approves execution.
+ */
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+const execAsync = promisify(exec);
+/**
+ * Generate a deploy preview for the given action.
+ *
+ * Dispatches to the appropriate provider-specific preview generator
+ * based on the action keyword (terraform, kubectl/kubernetes, or helm).
+ *
+ * @param action - The action keyword (e.g., "terraform apply", "kubectl apply", "helm install")
+ * @param workdir - Working directory containing the IaC files
+ * @returns DeployPreview result
+ */
+export async function generateDeployPreview(action, workdir) {
+    const actionLower = action.toLowerCase();
+    if (actionLower.includes('terraform')) {
+        return generateTerraformPreview(workdir);
+    }
+    if (actionLower.includes('kubectl') || actionLower.includes('kubernetes')) {
+        return generateKubectlPreview(action, workdir);
+    }
+    if (actionLower.includes('helm')) {
+        return generateHelmPreview(action, workdir);
+    }
+    return {
+        tool: 'unknown',
+        action,
+        workdir,
+        changes: [],
+        summary: { toCreate: 0, toUpdate: 0, toDestroy: 0, toReplace: 0, unchanged: 0 },
+        rawOutput: '',
+        success: false,
+        error: `Unsupported action for deploy preview: ${action}`,
+    };
+}
+/**
+ * Format a deploy preview into a human-readable string.
+ *
+ * Produces a summary block with change counts, a detailed change list
+ * using +/~/- symbols, optional cost impact, and a blast-radius warning
+ * when destructive operations are present.
+ *
+ * @param preview - The deploy preview to format
+ * @returns Formatted multi-line string suitable for terminal display
+ */
+export function formatDeployPreview(preview) {
+    if (!preview.success) {
+        return `Deploy Preview Failed\n${'='.repeat(40)}\n\nError: ${preview.error}\n`;
+    }
+    const lines = [];
+    lines.push(`Deploy Preview: ${preview.tool} ${preview.action}`);
+    lines.push('='.repeat(50));
+    lines.push(`Working directory: ${preview.workdir}`);
+    lines.push('');
+    // Summary
+    const { toCreate, toUpdate, toDestroy, toReplace, unchanged } = preview.summary;
+    lines.push('Summary:');
+    if (toCreate > 0) {
+        lines.push(`  + ${toCreate} to create`);
+    }
+    if (toUpdate > 0) {
+        lines.push(`  ~ ${toUpdate} to update`);
+    }
+    if (toReplace > 0) {
+        lines.push(`  +/- ${toReplace} to replace`);
+    }
+    if (toDestroy > 0) {
+        lines.push(`  - ${toDestroy} to destroy`);
+    }
+    if (unchanged > 0) {
+        lines.push(`  = ${unchanged} unchanged`);
+    }
+    lines.push('');
+    // Detailed changes
+    if (preview.changes.length > 0) {
+        lines.push('Changes:');
+        for (const change of preview.changes) {
+            const symbol = getChangeSymbol(change.action);
+            const detail = change.details ? ` (${change.details})` : '';
+            lines.push(`  ${symbol} ${change.resource}${detail}`);
+        }
+        lines.push('');
+    }
+    // Cost impact
+    if (preview.costImpact) {
+        lines.push(`Cost Impact: ${preview.costImpact}`);
+        lines.push('');
+    }
+    // Blast radius warning
+    if (toDestroy > 0) {
+        lines.push('WARNING: This operation will DESTROY resources.');
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------
+// Provider-specific preview generators
+// ---------------------------------------------------------------
+/**
+ * Run `terraform plan` and parse the human-readable output into
+ * structured {@link ResourceChange} entries.
+ */
+async function generateTerraformPreview(workdir) {
+    const base = {
+        tool: 'terraform',
+        action: 'apply',
+        workdir,
+    };
+    try {
+        // Run terraform plan with JSON output
+        const { stdout, stderr } = await execAsync('terraform plan -no-color -detailed-exitcode 2>&1 || true', { cwd: workdir, timeout: 300_000, maxBuffer: 10 * 1024 * 1024 });
+        const output = stdout || stderr;
+        const changes = parseTerraformPlanOutput(output);
+        const summary = summarizeChanges(changes);
+        // Try infracost for real cost delta (best-effort, non-blocking)
+        let costImpact;
+        try {
+            const { stdout: icOut } = await execAsync(`infracost breakdown --path ${workdir} --format json`, { timeout: 60_000, maxBuffer: 5 * 1024 * 1024 });
+            const ic = JSON.parse(icOut);
+            const totalMonthly = parseFloat(ic.totalMonthlyCost ?? '0').toFixed(2);
+            const diff = parseFloat(ic.diffTotalMonthlyCost ?? '0');
+            const sign = diff > 0 ? '+' : '';
+            costImpact = `$${totalMonthly}/month${diff !== 0 ? ` (${sign}$${diff.toFixed(2)} change)` : ' (no change)'}`;
+        }
+        catch {
+            // infracost not installed or failed — omit cost impact
+        }
+        return {
+            ...base,
+            changes,
+            summary,
+            rawOutput: output,
+            costImpact,
+            success: true,
+        };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+            ...base,
+            changes: [],
+            summary: { toCreate: 0, toUpdate: 0, toDestroy: 0, toReplace: 0, unchanged: 0 },
+            rawOutput: '',
+            success: false,
+            error: msg,
+        };
+    }
+}
+/**
+ * Run `kubectl diff` against the current cluster state and parse
+ * the unified-diff output into {@link ResourceChange} entries.
+ */
+async function generateKubectlPreview(action, workdir) {
+    const base = {
+        tool: 'kubectl',
+        action,
+        workdir,
+    };
+    try {
+        const { stdout } = await execAsync('kubectl diff -f . 2>&1 || true', {
+            cwd: workdir,
+            timeout: 60_000,
+            maxBuffer: 10 * 1024 * 1024,
+        });
+        const changes = parseKubectlDiffOutput(stdout);
+        const summary = summarizeChanges(changes);
+        return {
+            ...base,
+            changes,
+            summary,
+            rawOutput: stdout,
+            success: true,
+        };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+            ...base,
+            changes: [],
+            summary: { toCreate: 0, toUpdate: 0, toDestroy: 0, toReplace: 0, unchanged: 0 },
+            rawOutput: '',
+            success: false,
+            error: msg,
+        };
+    }
+}
+/**
+ * Run `helm template` to render the chart locally and report the
+ * rendered manifests as a single create change.
+ */
+async function generateHelmPreview(action, workdir) {
+    const base = {
+        tool: 'helm',
+        action,
+        workdir,
+    };
+    try {
+        // Use helm template to show what would be deployed
+        const { stdout } = await execAsync('helm template . 2>&1', {
+            cwd: workdir,
+            timeout: 60_000,
+            maxBuffer: 10 * 1024 * 1024,
+        });
+        return {
+            ...base,
+            changes: [{ resource: 'helm-chart', action: 'create', details: 'Template rendered' }],
+            summary: { toCreate: 1, toUpdate: 0, toDestroy: 0, toReplace: 0, unchanged: 0 },
+            rawOutput: stdout,
+            success: true,
+        };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+            ...base,
+            changes: [],
+            summary: { toCreate: 0, toUpdate: 0, toDestroy: 0, toReplace: 0, unchanged: 0 },
+            rawOutput: '',
+            success: false,
+            error: msg,
+        };
+    }
+}
+// ---------------------------------------------------------------
+// G9: Multi-file diff batch builder for Terraform plan output
+// ---------------------------------------------------------------
+/**
+ * G9: Build a FileDiffBatch from a Terraform plan preview.
+ *
+ * Parses the resource changes in the plan and represents each modified
+ * resource as a synthetic diff entry so they can be reviewed via the
+ * existing FileDiffModal batch flow.
+ *
+ * @param preview - DeployPreview from generateTerraformPreview
+ * @returns Array of file-diff entries suitable for FileDiffBatch.files
+ */
+export function buildFileDiffBatchFromPlan(preview) {
+    return preview.changes.map(change => {
+        const actionLine = getChangeSymbolStr(change.action);
+        const diff = [
+            `--- a/${change.resource}`,
+            `+++ b/${change.resource}`,
+            `@@ -0,0 +1,1 @@`,
+            `${actionLine} ${change.resource}${change.details ? `  # ${change.details}` : ''}`,
+        ].join('\n');
+        return {
+            filePath: change.resource,
+            diff,
+            toolName: 'terraform',
+        };
+    });
+}
+function getChangeSymbolStr(action) {
+    switch (action) {
+        case 'create': return '+';
+        case 'update': return '~';
+        case 'destroy': return '-';
+        case 'replace': return '+/-';
+        default: return ' ';
+    }
+}
+// ---------------------------------------------------------------
+// Output parsers
+// ---------------------------------------------------------------
+/**
+ * Parse the human-readable `terraform plan` output into structured
+ * {@link ResourceChange} entries.
+ *
+ * Recognises lines such as:
+ *   `# aws_instance.web will be created`
+ *   `# aws_instance.web will be updated in-place`
+ *   `# aws_instance.web will be destroyed`
+ *   `# aws_instance.web must be replaced`
+ *
+ * Falls back to the summary line (`Plan: X to add, Y to change, Z to destroy.`)
+ * when no individual resource lines are found.
+ */
+export function parseTerraformPlanOutput(output) {
+    const changes = [];
+    const lines = output.split('\n');
+    for (const line of lines) {
+        // Match lines like: "  # aws_instance.web will be created"
+        const createMatch = line.match(/^\s*#\s+(\S+)\s+will be created/);
+        if (createMatch) {
+            changes.push({ resource: createMatch[1], action: 'create' });
+            continue;
+        }
+        const updateMatch = line.match(/^\s*#\s+(\S+)\s+will be updated/);
+        if (updateMatch) {
+            changes.push({ resource: updateMatch[1], action: 'update' });
+            continue;
+        }
+        const destroyMatch = line.match(/^\s*#\s+(\S+)\s+will be destroyed/);
+        if (destroyMatch) {
+            changes.push({ resource: destroyMatch[1], action: 'destroy' });
+            continue;
+        }
+        const replaceMatch = line.match(/^\s*#\s+(\S+)\s+must be replaced/);
+        if (replaceMatch) {
+            changes.push({ resource: replaceMatch[1], action: 'replace' });
+            continue;
+        }
+        // Also match: "Plan: X to add, Y to change, Z to destroy."
+        const summaryMatch = line.match(/Plan:\s+(\d+)\s+to add,\s+(\d+)\s+to change,\s+(\d+)\s+to destroy/);
+        if (summaryMatch && changes.length === 0) {
+            // If we didn't find specific resources, create generic entries
+            const toAdd = parseInt(summaryMatch[1]);
+            const toChange = parseInt(summaryMatch[2]);
+            const toDestroy = parseInt(summaryMatch[3]);
+            for (let i = 0; i < toAdd; i++) {
+                changes.push({ resource: `resource_${i + 1}`, action: 'create' });
+            }
+            for (let i = 0; i < toChange; i++) {
+                changes.push({ resource: `resource_${toAdd + i + 1}`, action: 'update' });
+            }
+            for (let i = 0; i < toDestroy; i++) {
+                changes.push({ resource: `resource_${toAdd + toChange + i + 1}`, action: 'destroy' });
+            }
+        }
+    }
+    return changes;
+}
+/**
+ * Parse `kubectl diff` unified-diff output into structured
+ * {@link ResourceChange} entries.
+ *
+ * Each `diff -u` header is treated as a separate resource update.
+ * An empty or "no changes" output yields an empty array.
+ */
+function parseKubectlDiffOutput(output) {
+    const changes = [];
+    const resourceRegex = /^diff -u.*\/(\S+)/gm;
+    let match;
+    while ((match = resourceRegex.exec(output)) !== null) {
+        changes.push({ resource: match[1], action: 'update' });
+    }
+    // If output is empty, no changes
+    if (output.trim() === '' || output.includes('no changes')) {
+        return [];
+    }
+    // If we found no specific resources but have output, assume updates
+    if (changes.length === 0 && output.trim().length > 0) {
+        changes.push({ resource: 'kubernetes-resources', action: 'update' });
+    }
+    return changes;
+}
+/**
+ * Aggregate an array of {@link ResourceChange} entries into the
+ * summary counts used by {@link DeployPreview}.
+ */
+function summarizeChanges(changes) {
+    return {
+        toCreate: changes.filter(c => c.action === 'create').length,
+        toUpdate: changes.filter(c => c.action === 'update').length,
+        toDestroy: changes.filter(c => c.action === 'destroy').length,
+        toReplace: changes.filter(c => c.action === 'replace').length,
+        unchanged: changes.filter(c => c.action === 'no-op').length,
+    };
+}
+/**
+ * Map a {@link ResourceChange} action to a single-character symbol
+ * for display in the formatted preview.
+ *
+ * | Action    | Symbol |
+ * |-----------|--------|
+ * | create    | `+`    |
+ * | update    | `~`    |
+ * | destroy   | `-`    |
+ * | replace   | `+/-`  |
+ * | read      | `>`    |
+ * | no-op     | `=`    |
+ */
+function getChangeSymbol(action) {
+    switch (action) {
+        case 'create':
+            return '+';
+        case 'update':
+            return '~';
+        case 'destroy':
+            return '-';
+        case 'replace':
+            return '+/-';
+        case 'read':
+            return '>';
+        case 'no-op':
+            return '=';
+    }
+}

package/dist/src/agent/expand-files.js

@@ -0,0 +1,95 @@
+/**
+ * Shared @file reference expansion utility.
+ *
+ * Replaces @path/to/file references in a prompt with the file contents
+ * wrapped in <file> tags. Files larger than 10KB are truncated.
+ *
+ * Security: blocks path traversal (../../etc/passwd) and sensitive file patterns.
+ *
+ * Special tokens (G22):
+ *   @workspace — concatenates all .tf files in cwd (up to 50KB)
+ *   @cluster   — instructs the agent to use the kubectl tool (async call not possible here)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** Sensitive file patterns that should never be expanded. */
+const SENSITIVE_FILE_RE = /(\.env|\.pem|\.key|\.p12|\.pfx|id_rsa|id_ed25519|credentials|\.netrc)$/i;
+/**
+ * Expand @file references in a prompt string.
+ * Replaces @path/to/file with the file contents wrapped in <file> tags.
+ * Files larger than 10KB are truncated.
+ *
+ * Security: blocks path traversal outside the project root and sensitive
+ * file patterns (.env, .pem, .key, credentials, etc.).
+ */
+export function expandFileReferences(text, cwd = process.cwd()) {
+    const fileRefs = text.match(/@([\w./_-]+)/g);
+    if (!fileRefs)
+        return text;
+    let expanded = text;
+    // G22: Handle @workspace special token — concatenate all .tf files
+    if (expanded.includes('@workspace')) {
+        try {
+            const tfFiles = fs.readdirSync(cwd).filter(f => f.endsWith('.tf'));
+            if (tfFiles.length > 0) {
+                const parts = [];
+                let totalSize = 0;
+                const MAX_SIZE = 50_000;
+                for (const file of tfFiles) {
+                    if (totalSize >= MAX_SIZE) {
+                        parts.push('... [truncated — 50KB limit reached]');
+                        break;
+                    }
+                    try {
+                        const content = fs.readFileSync(path.join(cwd, file), 'utf-8');
+                        parts.push(`\n<file path="${file}">\n${content.slice(0, Math.min(content.length, MAX_SIZE - totalSize))}\n</file>`);
+                        totalSize += content.length;
+                    }
+                    catch { /* skip unreadable files */ }
+                }
+                expanded = expanded.replace('@workspace', parts.join('\n'));
+            }
+            else {
+                expanded = expanded.replace('@workspace', '[No .tf files found in current directory]');
+            }
+        }
+        catch {
+            expanded = expanded.replace('@workspace', '[Error reading workspace files]');
+        }
+    }
+    // G22: Handle @cluster special token — kubectl get all
+    // @cluster requires an async kubectl call — guide agent to use the kubectl tool instead
+    if (expanded.includes('@cluster')) {
+        expanded = expanded.replace('@cluster', '[Use the kubectl tool with action=get and args="all -A" to retrieve cluster resources]');
+    }
+    for (const ref of fileRefs) {
+        // Skip special tokens already handled above
+        if (ref === '@workspace' || ref === '@cluster') {
+            continue;
+        }
+        const filePath = ref.slice(1);
+        try {
+            const resolved = path.resolve(cwd, filePath);
+            // Security: block path traversal outside project root
+            const rel = path.relative(cwd, resolved);
+            if (rel.startsWith('..') || path.isAbsolute(rel)) {
+                expanded = expanded.replace(ref, `[File blocked: path "${filePath}" is outside the project directory]`);
+                continue;
+            }
+            // Security: block sensitive file patterns
+            if (SENSITIVE_FILE_RE.test(resolved)) {
+                expanded = expanded.replace(ref, `[File blocked: "${filePath}" matches sensitive file pattern]`);
+                continue;
+            }
+            const content = fs.readFileSync(resolved, 'utf-8');
+            const truncated = content.length > 10_000
+                ? `${content.slice(0, 10_000)}\n... (truncated — showing 10,000 of ${content.length.toLocaleString()} chars)`
+                : content;
+            expanded = expanded.replace(ref, `\n<file path="${filePath}">\n${truncated}\n</file>`);
+        }
+        catch {
+            // File not found — leave the @reference as-is
+        }
+    }
+    return expanded;
+}

package/dist/src/agent/index.js

@@ -0,0 +1,18 @@
+/**
+ * Agent System — Barrel re-exports
+ *
+ * Core agentic loop, system prompt builder, permission engine,
+ * context manager, and subagent system.
+ */
+// Core agentic loop
+export { runAgentLoop, getToolsForMode, } from './loop';
+// System prompt builder
+export { buildSystemPrompt, loadNimbusMd, } from './system-prompt';
+// Permission engine
+export { checkPermission, createPermissionState, approveForSession, approveActionForSession, } from './permissions';
+// Context manager — @file/@folder reference resolution
+export { resolveReferences, buildContextInjection, fuzzyFileSearch, } from './context';
+// Deploy preview system
+export { generateDeployPreview, formatDeployPreview, } from './deploy-preview';
+// Subagent system
+export { Subagent, createSubagent, parseAgentMention, createExploreSubagent, createInfraSubagent, createSecuritySubagent, createCostSubagent, createGeneralSubagent, } from './subagents';