npm - @build-astron-co/nimbus - Versions diffs - 0.2.0 - Mend

@build-astron-co/nimbus 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (313) hide show

package/LICENSE +21 -0
package/README.md +628 -0
package/bin/nimbus +38 -0
package/package.json +80 -0
package/src/__tests__/app.test.ts +76 -0
package/src/__tests__/audit.test.ts +877 -0
package/src/__tests__/circuit-breaker.test.ts +116 -0
package/src/__tests__/cli-run.test.ts +115 -0
package/src/__tests__/context-manager.test.ts +502 -0
package/src/__tests__/context.test.ts +242 -0
package/src/__tests__/enterprise.test.ts +401 -0
package/src/__tests__/generator.test.ts +433 -0
package/src/__tests__/hooks.test.ts +582 -0
package/src/__tests__/init.test.ts +436 -0
package/src/__tests__/intent-parser.test.ts +229 -0
package/src/__tests__/llm-router.test.ts +209 -0
package/src/__tests__/lsp.test.ts +293 -0
package/src/__tests__/modes.test.ts +336 -0
package/src/__tests__/permissions.test.ts +338 -0
package/src/__tests__/serve.test.ts +275 -0
package/src/__tests__/sessions.test.ts +227 -0
package/src/__tests__/sharing.test.ts +288 -0
package/src/__tests__/snapshots.test.ts +581 -0
package/src/__tests__/state-db.test.ts +334 -0
package/src/__tests__/stream-with-tools.test.ts +732 -0
package/src/__tests__/subagents.test.ts +176 -0
package/src/__tests__/system-prompt.test.ts +169 -0
package/src/__tests__/tool-converter.test.ts +256 -0
package/src/__tests__/tool-schemas.test.ts +397 -0
package/src/__tests__/tools.test.ts +143 -0
package/src/__tests__/version.test.ts +49 -0
package/src/agent/compaction-agent.ts +227 -0
package/src/agent/context-manager.ts +435 -0
package/src/agent/context.ts +427 -0
package/src/agent/deploy-preview.ts +426 -0
package/src/agent/index.ts +68 -0
package/src/agent/loop.ts +717 -0
package/src/agent/modes.ts +429 -0
package/src/agent/permissions.ts +466 -0
package/src/agent/subagents/base.ts +116 -0
package/src/agent/subagents/cost.ts +51 -0
package/src/agent/subagents/explore.ts +42 -0
package/src/agent/subagents/general.ts +54 -0
package/src/agent/subagents/index.ts +102 -0
package/src/agent/subagents/infra.ts +59 -0
package/src/agent/subagents/security.ts +69 -0
package/src/agent/system-prompt.ts +436 -0
package/src/app.ts +122 -0
package/src/audit/activity-log.ts +290 -0
package/src/audit/compliance-checker.ts +540 -0
package/src/audit/cost-tracker.ts +318 -0
package/src/audit/index.ts +23 -0
package/src/audit/security-scanner.ts +596 -0
package/src/auth/guard.ts +75 -0
package/src/auth/index.ts +56 -0
package/src/auth/oauth.ts +455 -0
package/src/auth/providers.ts +470 -0
package/src/auth/sso.ts +113 -0
package/src/auth/store.ts +505 -0
package/src/auth/types.ts +187 -0
package/src/build.ts +141 -0
package/src/cli/index.ts +16 -0
package/src/cli/init.ts +854 -0
package/src/cli/openapi-spec.ts +356 -0
package/src/cli/run.ts +237 -0
package/src/cli/serve-auth.ts +80 -0
package/src/cli/serve.ts +462 -0
package/src/cli/web.ts +67 -0
package/src/cli.ts +1417 -0
package/src/clients/core-engine-client.ts +227 -0
package/src/clients/enterprise-client.ts +334 -0
package/src/clients/generator-client.ts +351 -0
package/src/clients/git-client.ts +627 -0
package/src/clients/github-client.ts +410 -0
package/src/clients/helm-client.ts +504 -0
package/src/clients/index.ts +80 -0
package/src/clients/k8s-client.ts +497 -0
package/src/clients/llm-client.ts +161 -0
package/src/clients/rest-client.ts +130 -0
package/src/clients/service-discovery.ts +33 -0
package/src/clients/terraform-client.ts +482 -0
package/src/clients/tools-client.ts +1843 -0
package/src/clients/ws-client.ts +115 -0
package/src/commands/analyze/index.ts +352 -0
package/src/commands/apply/helm.ts +473 -0
package/src/commands/apply/index.ts +213 -0
package/src/commands/apply/k8s.ts +454 -0
package/src/commands/apply/terraform.ts +582 -0
package/src/commands/ask.ts +167 -0
package/src/commands/audit/index.ts +238 -0
package/src/commands/auth-cloud.ts +294 -0
package/src/commands/auth-list.ts +134 -0
package/src/commands/auth-profile.ts +121 -0
package/src/commands/auth-status.ts +141 -0
package/src/commands/aws/ec2.ts +501 -0
package/src/commands/aws/iam.ts +397 -0
package/src/commands/aws/index.ts +133 -0
package/src/commands/aws/lambda.ts +396 -0
package/src/commands/aws/rds.ts +439 -0
package/src/commands/aws/s3.ts +439 -0
package/src/commands/aws/vpc.ts +393 -0
package/src/commands/aws-discover.ts +649 -0
package/src/commands/aws-terraform.ts +805 -0
package/src/commands/azure/aks.ts +376 -0
package/src/commands/azure/functions.ts +253 -0
package/src/commands/azure/index.ts +116 -0
package/src/commands/azure/storage.ts +478 -0
package/src/commands/azure/vm.ts +355 -0
package/src/commands/billing/index.ts +256 -0
package/src/commands/chat.ts +314 -0
package/src/commands/config.ts +346 -0
package/src/commands/cost/cloud-cost-estimator.ts +266 -0
package/src/commands/cost/estimator.ts +79 -0
package/src/commands/cost/index.ts +594 -0
package/src/commands/cost/parsers/terraform.ts +273 -0
package/src/commands/cost/parsers/types.ts +25 -0
package/src/commands/cost/pricing/aws.ts +544 -0
package/src/commands/cost/pricing/azure.ts +499 -0
package/src/commands/cost/pricing/gcp.ts +396 -0
package/src/commands/cost/pricing/index.ts +40 -0
package/src/commands/demo.ts +250 -0
package/src/commands/doctor.ts +794 -0
package/src/commands/drift/index.ts +439 -0
package/src/commands/explain.ts +277 -0
package/src/commands/feedback.ts +389 -0
package/src/commands/fix.ts +324 -0
package/src/commands/fs/index.ts +402 -0
package/src/commands/gcp/compute.ts +325 -0
package/src/commands/gcp/functions.ts +271 -0
package/src/commands/gcp/gke.ts +438 -0
package/src/commands/gcp/iam.ts +344 -0
package/src/commands/gcp/index.ts +129 -0
package/src/commands/gcp/storage.ts +284 -0
package/src/commands/generate-helm.ts +1249 -0
package/src/commands/generate-k8s.ts +1560 -0
package/src/commands/generate-terraform.ts +1460 -0
package/src/commands/gh/index.ts +863 -0
package/src/commands/git/index.ts +1343 -0
package/src/commands/helm/index.ts +1126 -0
package/src/commands/help.ts +539 -0
package/src/commands/history.ts +142 -0
package/src/commands/import.ts +868 -0
package/src/commands/index.ts +367 -0
package/src/commands/init.ts +1046 -0
package/src/commands/k8s/index.ts +1137 -0
package/src/commands/login.ts +631 -0
package/src/commands/logout.ts +83 -0
package/src/commands/onboarding.ts +228 -0
package/src/commands/plan/display.ts +279 -0
package/src/commands/plan/index.ts +599 -0
package/src/commands/preview.ts +452 -0
package/src/commands/questionnaire.ts +1270 -0
package/src/commands/resume.ts +55 -0
package/src/commands/team/index.ts +346 -0
package/src/commands/template.ts +232 -0
package/src/commands/tf/index.ts +1034 -0
package/src/commands/upgrade.ts +550 -0
package/src/commands/usage/index.ts +134 -0
package/src/commands/version.ts +170 -0
package/src/compat/index.ts +2 -0
package/src/compat/runtime.ts +12 -0
package/src/compat/sqlite.ts +107 -0
package/src/config/index.ts +17 -0
package/src/config/manager.ts +530 -0
package/src/config/safety-policy.ts +358 -0
package/src/config/schema.ts +125 -0
package/src/config/types.ts +527 -0
package/src/context/context-db.ts +199 -0
package/src/demo/index.ts +349 -0
package/src/demo/scenarios/full-journey.ts +229 -0
package/src/demo/scenarios/getting-started.ts +127 -0
package/src/demo/scenarios/helm-release.ts +341 -0
package/src/demo/scenarios/k8s-deployment.ts +194 -0
package/src/demo/scenarios/terraform-vpc.ts +170 -0
package/src/demo/types.ts +92 -0
package/src/engine/cost-estimator.ts +438 -0
package/src/engine/diagram-generator.ts +256 -0
package/src/engine/drift-detector.ts +902 -0
package/src/engine/executor.ts +1035 -0
package/src/engine/index.ts +76 -0
package/src/engine/orchestrator.ts +636 -0
package/src/engine/planner.ts +720 -0
package/src/engine/safety.ts +743 -0
package/src/engine/verifier.ts +770 -0
package/src/enterprise/audit.ts +348 -0
package/src/enterprise/auth.ts +270 -0
package/src/enterprise/billing.ts +822 -0
package/src/enterprise/index.ts +17 -0
package/src/enterprise/teams.ts +443 -0
package/src/generator/best-practices.ts +1608 -0
package/src/generator/helm.ts +630 -0
package/src/generator/index.ts +37 -0
package/src/generator/intent-parser.ts +514 -0
package/src/generator/kubernetes.ts +976 -0
package/src/generator/terraform.ts +1867 -0
package/src/history/index.ts +8 -0
package/src/history/manager.ts +322 -0
package/src/history/types.ts +34 -0
package/src/hooks/config.ts +432 -0
package/src/hooks/engine.ts +391 -0
package/src/hooks/index.ts +4 -0
package/src/llm/auth-bridge.ts +198 -0
package/src/llm/circuit-breaker.ts +140 -0
package/src/llm/config-loader.ts +201 -0
package/src/llm/cost-calculator.ts +171 -0
package/src/llm/index.ts +8 -0
package/src/llm/model-aliases.ts +115 -0
package/src/llm/provider-registry.ts +63 -0
package/src/llm/providers/anthropic.ts +433 -0
package/src/llm/providers/bedrock.ts +477 -0
package/src/llm/providers/google.ts +405 -0
package/src/llm/providers/ollama.ts +767 -0
package/src/llm/providers/openai-compatible.ts +340 -0
package/src/llm/providers/openai.ts +328 -0
package/src/llm/providers/openrouter.ts +338 -0
package/src/llm/router.ts +1035 -0
package/src/llm/types.ts +232 -0
package/src/lsp/client.ts +298 -0
package/src/lsp/languages.ts +116 -0
package/src/lsp/manager.ts +278 -0
package/src/mcp/client.ts +402 -0
package/src/mcp/index.ts +5 -0
package/src/mcp/manager.ts +133 -0
package/src/nimbus.ts +214 -0
package/src/plugins/index.ts +27 -0
package/src/plugins/loader.ts +334 -0
package/src/plugins/manager.ts +376 -0
package/src/plugins/types.ts +284 -0
package/src/scanners/cicd-scanner.ts +258 -0
package/src/scanners/cloud-scanner.ts +466 -0
package/src/scanners/framework-scanner.ts +469 -0
package/src/scanners/iac-scanner.ts +388 -0
package/src/scanners/index.ts +539 -0
package/src/scanners/language-scanner.ts +276 -0
package/src/scanners/package-manager-scanner.ts +277 -0
package/src/scanners/types.ts +172 -0
package/src/sessions/manager.ts +365 -0
package/src/sessions/types.ts +44 -0
package/src/sharing/sync.ts +296 -0
package/src/sharing/viewer.ts +97 -0
package/src/snapshots/index.ts +2 -0
package/src/snapshots/manager.ts +530 -0
package/src/state/artifacts.ts +147 -0
package/src/state/audit.ts +137 -0
package/src/state/billing.ts +240 -0
package/src/state/checkpoints.ts +117 -0
package/src/state/config.ts +67 -0
package/src/state/conversations.ts +14 -0
package/src/state/credentials.ts +154 -0
package/src/state/db.ts +58 -0
package/src/state/index.ts +26 -0
package/src/state/messages.ts +115 -0
package/src/state/projects.ts +123 -0
package/src/state/schema.ts +236 -0
package/src/state/sessions.ts +147 -0
package/src/state/teams.ts +200 -0
package/src/telemetry.ts +108 -0
package/src/tools/aws-ops.ts +952 -0
package/src/tools/azure-ops.ts +579 -0
package/src/tools/file-ops.ts +593 -0
package/src/tools/gcp-ops.ts +625 -0
package/src/tools/git-ops.ts +773 -0
package/src/tools/github-ops.ts +799 -0
package/src/tools/helm-ops.ts +943 -0
package/src/tools/index.ts +17 -0
package/src/tools/k8s-ops.ts +819 -0
package/src/tools/schemas/converter.ts +184 -0
package/src/tools/schemas/devops.ts +612 -0
package/src/tools/schemas/index.ts +73 -0
package/src/tools/schemas/standard.ts +1144 -0
package/src/tools/schemas/types.ts +705 -0
package/src/tools/terraform-ops.ts +862 -0
package/src/types/ambient.d.ts +193 -0
package/src/types/config.ts +83 -0
package/src/types/drift.ts +116 -0
package/src/types/enterprise.ts +335 -0
package/src/types/index.ts +20 -0
package/src/types/plan.ts +44 -0
package/src/types/request.ts +65 -0
package/src/types/response.ts +54 -0
package/src/types/service.ts +51 -0
package/src/ui/App.tsx +997 -0
package/src/ui/DeployPreview.tsx +169 -0
package/src/ui/Header.tsx +68 -0
package/src/ui/InputBox.tsx +350 -0
package/src/ui/MessageList.tsx +585 -0
package/src/ui/PermissionPrompt.tsx +151 -0
package/src/ui/StatusBar.tsx +158 -0
package/src/ui/ToolCallDisplay.tsx +409 -0
package/src/ui/chat-ui.ts +853 -0
package/src/ui/index.ts +33 -0
package/src/ui/ink/index.ts +711 -0
package/src/ui/streaming.ts +176 -0
package/src/ui/types.ts +57 -0
package/src/utils/analytics.ts +72 -0
package/src/utils/cost-warning.ts +27 -0
package/src/utils/env.ts +46 -0
package/src/utils/errors.ts +69 -0
package/src/utils/event-bus.ts +38 -0
package/src/utils/index.ts +24 -0
package/src/utils/logger.ts +171 -0
package/src/utils/rate-limiter.ts +121 -0
package/src/utils/service-auth.ts +49 -0
package/src/utils/validation.ts +53 -0
package/src/version.ts +4 -0
package/src/watcher/index.ts +163 -0
package/src/wizard/approval.ts +383 -0
package/src/wizard/index.ts +25 -0
package/src/wizard/prompts.ts +338 -0
package/src/wizard/types.ts +171 -0
package/src/wizard/ui.ts +556 -0
package/src/wizard/wizard.ts +304 -0
package/tsconfig.json +24 -0

package/src/sharing/viewer.ts ADDED Viewed

@@ -0,0 +1,97 @@
+/**
+ * Minimal HTML viewer for shared sessions.
+ *
+ * Generates a standalone HTML page that can be served by nimbus serve
+ * for viewing shared sessions when the Web UI is not available.
+ */
+import type { SharedSession } from './sync';
+/**
+ * Generate a standalone HTML page for viewing a shared session.
+ */
+export function generateShareViewer(shared: SharedSession): string {
+  const messagesHtml = shared.messages
+    .filter(m => m.role === 'user' || m.role === 'assistant')
+    .map(m => {
+      const isUser = m.role === 'user';
+      const bgColor = isUser ? '#3b82f6' : '#1e293b';
+      const align = isUser ? 'flex-end' : 'flex-start';
+      const content =
+        typeof m.content === 'string'
+          ? escapeHtml(m.content)
+          : escapeHtml(JSON.stringify(m.content));
+      return `
+        <div style="display:flex;justify-content:${align};margin:8px 0">
+          <div style="max-width:75%;padding:12px 16px;border-radius:16px;background:${bgColor};color:#e2e8f0;font-size:14px;line-height:1.6;white-space:pre-wrap;word-break:break-word">
+            ${content}
+          </div>
+        </div>`;
+    })
+    .join('\n');
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Nimbus Session: ${escapeHtml(shared.name)}</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      background: #0a0e1a;
+      color: #e2e8f0;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      min-height: 100vh;
+    }
+    .header {
+      border-bottom: 1px solid rgba(255,255,255,0.1);
+      padding: 16px 24px;
+      display: flex;
+      align-items: center;
+      gap: 12px;
+    }
+    .logo { color: #22d3ee; font-weight: bold; font-size: 18px; }
+    .title { color: #94a3b8; font-size: 14px; }
+    .meta { color: #64748b; font-size: 12px; margin-left: auto; }
+    .messages { max-width: 800px; margin: 0 auto; padding: 24px; }
+    .badge {
+      display: inline-block; padding: 2px 8px; border-radius: 9999px;
+      font-size: 11px; font-weight: 500; background: rgba(34,211,238,0.1);
+      color: #22d3ee; border: 1px solid rgba(34,211,238,0.2);
+    }
+    .footer {
+      border-top: 1px solid rgba(255,255,255,0.1);
+      padding: 16px 24px; text-align: center;
+      color: #64748b; font-size: 12px;
+    }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <span class="logo">Nimbus</span>
+    <span class="title">${escapeHtml(shared.name)}</span>
+    <span class="badge">${escapeHtml(shared.mode)}</span>
+    ${shared.isLive ? '<span class="badge" style="background:rgba(16,185,129,0.1);color:#10b981;border-color:rgba(16,185,129,0.2)">LIVE</span>' : ''}
+    <span class="meta">${shared.model} &bull; $${shared.costUSD.toFixed(4)} &bull; ${shared.tokenCount.toLocaleString()} tokens</span>
+  </div>
+  <div class="messages">
+    ${messagesHtml}
+  </div>
+  <div class="footer">
+    Shared via Nimbus &bull; Created ${new Date(shared.createdAt).toLocaleString()} &bull; Expires ${new Date(shared.expiresAt).toLocaleString()}
+  </div>
+</body>
+</html>`;
+}
+/** Escape HTML special characters. */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}

package/src/snapshots/index.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export { SnapshotManager } from './manager';
2	+ export type { Snapshot, SnapshotManagerOptions } from './manager';

package/src/snapshots/manager.ts ADDED Viewed

@@ -0,0 +1,530 @@
+/**
+ * Snapshot Manager
+ *
+ * Captures and restores file state using git tree objects (for git projects)
+ * or filesystem copies (for non-git projects). Supports undo/redo operations
+ * for file-modifying tool calls during a Nimbus CLI session.
+ */
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+const execAsync = promisify(exec);
+/** Default maximum number of snapshots to retain. */
+const DEFAULT_MAX_SNAPSHOTS = 100;
+/** Default maximum age for snapshots: 7 days in milliseconds. */
+const DEFAULT_MAX_AGE = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Directories and patterns to skip when copying files in non-git mode.
+ * These are typically large, generated, or internal directories that
+ * should not be included in snapshot copies.
+ */
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'coverage',
+  '.nimbus',
+  '.next',
+  '.cache',
+  '__pycache__',
+]);
+/**
+ * Shell command patterns that indicate file-modifying operations.
+ * Used by `shouldSnapshot` to detect bash commands that alter the filesystem.
+ */
+const FILE_MODIFYING_PATTERNS = [
+  /\brm\b/,
+  /\bmv\b/,
+  /\bcp\b/,
+  /\bchmod\b/,
+  /\bchown\b/,
+  /\bsed\b/,
+  /\bawk\b/,
+  /\bmkdir\b/,
+  /\brmdir\b/,
+  /\btouch\b/,
+  /\btruncate\b/,
+  /\bln\b/,
+  /\bunlink\b/,
+  />/, // redirect operators: >, >>, 2>, etc.
+];
+/**
+ * Tool names that always trigger a snapshot because they directly
+ * modify files on disk.
+ */
+const SNAPSHOT_TOOL_NAMES = new Set(['edit_file', 'multi_edit', 'write_file']);
+/**
+ * Represents a single point-in-time snapshot of the working tree state.
+ */
+export interface Snapshot {
+  /** Unique snapshot identifier (UUID v4). */
+  id: string;
+  /** Session ID that created this snapshot. */
+  sessionId: string;
+  /** Message ID associated with this snapshot. */
+  messageId: string;
+  /** Tool call ID that triggered this snapshot. */
+  toolCallId: string;
+  /** Git tree hash from `git write-tree`, or empty string for non-git projects. */
+  treeHash: string;
+  /** Timestamp when the snapshot was captured. */
+  timestamp: Date;
+  /** Human-readable description (e.g., "edit_file: src/server.ts"). */
+  description: string;
+  /** Whether this snapshot was captured from a git project. */
+  isGitProject: boolean;
+}
+/**
+ * Configuration options for the SnapshotManager.
+ */
+export interface SnapshotManagerOptions {
+  /** Absolute path to the project directory to manage snapshots for. */
+  projectDir: string;
+  /** Maximum number of snapshots to retain. Defaults to 100. */
+  maxSnapshots?: number;
+  /** Maximum age for snapshots in milliseconds. Defaults to 7 days. */
+  maxAge?: number;
+}
+/**
+ * Result of a restore, undo, or redo operation.
+ */
+interface SnapshotOperationResult {
+  /** Whether the operation succeeded. */
+  success: boolean;
+  /** Human-readable description of what was restored, or an error message. */
+  description: string;
+}
+/**
+ * Manages snapshots of the working tree for undo/redo support.
+ *
+ * For git-based projects, snapshots are captured as git tree objects using
+ * `git write-tree`, which records the full index state without creating a commit.
+ * Restoring reads the tree back into the index and checks out all files.
+ *
+ * For non-git projects, snapshots are stored as full directory copies under
+ * `.nimbus/snapshots/{id}/`, skipping large generated directories like
+ * `node_modules` and `dist`.
+ */
+export class SnapshotManager {
+  private readonly projectDir: string;
+  private readonly maxSnapshots: number;
+  private readonly maxAge: number;
+  private readonly isGitProject: boolean;
+  private readonly snapshotDir: string;
+  private snapshots: Snapshot[] = [];
+  private undoneSnapshots: Snapshot[] = [];
+  private nextId: number = 1;
+  constructor(options: SnapshotManagerOptions) {
+    this.projectDir = options.projectDir;
+    this.maxSnapshots = options.maxSnapshots ?? DEFAULT_MAX_SNAPSHOTS;
+    this.maxAge = options.maxAge ?? DEFAULT_MAX_AGE;
+    this.snapshotDir = path.join(options.projectDir, '.nimbus', 'snapshots');
+    // Detect if the project directory is a git repository
+    this.isGitProject = fs.existsSync(path.join(options.projectDir, '.git'));
+    // For non-git projects, ensure the snapshot directory exists
+    if (!this.isGitProject) {
+      fs.mkdirSync(this.snapshotDir, { recursive: true });
+    }
+  }
+  /**
+   * Capture a snapshot of the current working tree state.
+   *
+   * For git projects:
+   *   1. Creates a temporary git index and stages all changes into it
+   *   2. Captures a tree hash with `git write-tree` (no commit is created)
+   *   3. Removes the temporary index; the user's real staging area is untouched
+   *
+   * For non-git projects:
+   *   1. Creates a numbered snapshot directory under `.nimbus/snapshots/{id}/`
+   *   2. Recursively copies all tracked files, skipping `node_modules`,
+   *      `.git`, `dist`, `coverage`, and `.nimbus/snapshots`
+   *
+   * @param params - Metadata describing the tool call that triggered this snapshot.
+   * @returns The newly created Snapshot record.
+   */
+  async captureSnapshot(params: {
+    sessionId: string;
+    messageId: string;
+    toolCallId: string;
+    description: string;
+  }): Promise<Snapshot> {
+    const snapshotId = crypto.randomUUID();
+    let treeHash = '';
+    if (this.isGitProject) {
+      treeHash = await this.captureGitSnapshot();
+    } else {
+      await this.captureFilesystemSnapshot(snapshotId);
+    }
+    const snapshot: Snapshot = {
+      id: snapshotId,
+      sessionId: params.sessionId,
+      messageId: params.messageId,
+      toolCallId: params.toolCallId,
+      treeHash,
+      timestamp: new Date(),
+      description: params.description,
+      isGitProject: this.isGitProject,
+    };
+    this.snapshots.push(snapshot);
+    this.nextId++;
+    // Clear the redo stack whenever a new snapshot is captured,
+    // since the timeline has diverged
+    this.undoneSnapshots = [];
+    return snapshot;
+  }
+  /**
+   * Restore the working tree to the state recorded in a specific snapshot.
+   *
+   * For git projects:
+   *   Uses `git read-tree` and `git checkout-index -a -f` to replace the
+   *   working tree contents with the snapshot's tree hash.
+   *
+   * For non-git projects:
+   *   Copies files back from the snapshot directory, replacing current contents.
+   *
+   * @param snapshotId - The ID of the snapshot to restore.
+   * @returns An object indicating whether the restore succeeded and a description.
+   */
+  async restoreSnapshot(snapshotId: string): Promise<{ restored: boolean; description: string }> {
+    const snapshot = this.snapshots.find(s => s.id === snapshotId);
+    if (!snapshot) {
+      return { restored: false, description: `Snapshot ${snapshotId} not found` };
+    }
+    try {
+      if (snapshot.isGitProject) {
+        await this.restoreGitSnapshot(snapshot.treeHash);
+      } else {
+        await this.restoreFilesystemSnapshot(snapshot.id);
+      }
+      return { restored: true, description: `Restored snapshot: ${snapshot.description}` };
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { restored: false, description: `Failed to restore snapshot: ${message}` };
+    }
+  }
+  /**
+   * Undo the last file-modifying tool call by restoring the previous snapshot.
+   *
+   * Before restoring, the current working tree state is captured so that
+   * `redo()` can reverse the undo operation if needed.
+   *
+   * @returns An object indicating whether the undo succeeded and a description.
+   */
+  async undo(): Promise<SnapshotOperationResult> {
+    if (this.snapshots.length < 2) {
+      return { success: false, description: 'Nothing to undo' };
+    }
+    try {
+      // Pop the most recent snapshot (this is the state we are undoing)
+      const current = this.snapshots.pop()!;
+      // Push it onto the redo stack so we can redo later
+      this.undoneSnapshots.push(current);
+      // The snapshot we want to restore is now the last one in the stack
+      const target = this.snapshots[this.snapshots.length - 1];
+      if (target.isGitProject) {
+        await this.restoreGitSnapshot(target.treeHash);
+      } else {
+        await this.restoreFilesystemSnapshot(target.id);
+      }
+      return { success: true, description: `Undone: ${current.description}` };
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { success: false, description: `Undo failed: ${message}` };
+    }
+  }
+  /**
+   * Redo a previously undone snapshot.
+   *
+   * Pops the most recently undone snapshot from the redo stack and restores
+   * it, pushing it back onto the main snapshot stack.
+   *
+   * @returns An object indicating whether the redo succeeded and a description.
+   */
+  async redo(): Promise<SnapshotOperationResult> {
+    if (this.undoneSnapshots.length === 0) {
+      return { success: false, description: 'Nothing to redo' };
+    }
+    try {
+      const snapshot = this.undoneSnapshots.pop()!;
+      if (snapshot.isGitProject) {
+        await this.restoreGitSnapshot(snapshot.treeHash);
+      } else {
+        await this.restoreFilesystemSnapshot(snapshot.id);
+      }
+      // Push back onto main stack
+      this.snapshots.push(snapshot);
+      return { success: true, description: `Redone: ${snapshot.description}` };
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { success: false, description: `Redo failed: ${message}` };
+    }
+  }
+  /**
+   * Get snapshot history, optionally filtered to a specific session.
+   *
+   * @param sessionId - If provided, only return snapshots from this session.
+   * @returns An array of Snapshot records, ordered oldest to newest.
+   */
+  getHistory(sessionId?: string): Snapshot[] {
+    if (sessionId) {
+      return this.snapshots.filter(s => s.sessionId === sessionId);
+    }
+    return [...this.snapshots];
+  }
+  /**
+   * Get the total number of snapshots currently stored.
+   */
+  get count(): number {
+    return this.snapshots.length;
+  }
+  /**
+   * Clean up old snapshots that exceed `maxAge` or `maxSnapshots`.
+   *
+   * Snapshots older than `maxAge` are removed first, then the oldest
+   * snapshots are trimmed until the total count is at or below `maxSnapshots`.
+   * For non-git projects, the corresponding snapshot directories are also
+   * deleted from disk.
+   *
+   * @returns The number of snapshots that were removed.
+   */
+  async cleanup(): Promise<number> {
+    const now = Date.now();
+    const originalCount = this.snapshots.length;
+    // Remove snapshots older than maxAge
+    const expired = this.snapshots.filter(s => now - s.timestamp.getTime() > this.maxAge);
+    this.snapshots = this.snapshots.filter(s => now - s.timestamp.getTime() <= this.maxAge);
+    // Trim to maxSnapshots (keep most recent)
+    let trimmed: Snapshot[] = [];
+    if (this.snapshots.length > this.maxSnapshots) {
+      const excess = this.snapshots.length - this.maxSnapshots;
+      trimmed = this.snapshots.splice(0, excess);
+    }
+    // Clean up filesystem snapshot directories for non-git projects
+    const removed = [...expired, ...trimmed];
+    if (!this.isGitProject) {
+      for (const snapshot of removed) {
+        const snapshotPath = path.join(this.snapshotDir, snapshot.id);
+        try {
+          if (fs.existsSync(snapshotPath)) {
+            fs.rmSync(snapshotPath, { recursive: true, force: true });
+          }
+        } catch {
+          // Best-effort cleanup; do not throw on individual directory failures
+        }
+      }
+    }
+    // Also clean stale entries from the redo stack
+    this.undoneSnapshots = this.undoneSnapshots.filter(
+      s => now - s.timestamp.getTime() <= this.maxAge
+    );
+    return originalCount - this.snapshots.length;
+  }
+  /**
+   * Determine whether a tool call should trigger a snapshot capture.
+   *
+   * Returns `true` for tools that directly modify files:
+   * - `edit_file`, `multi_edit`, `write_file` always return true.
+   * - `bash` returns true if the command string contains patterns
+   *   indicative of file modification (rm, mv, cp, sed, redirect operators, etc.).
+   *
+   * @param toolName - The name of the tool being invoked.
+   * @param input - Optional input parameters for the tool call.
+   * @returns Whether a snapshot should be taken before this tool executes.
+   */
+  static shouldSnapshot(toolName: string, input?: Record<string, unknown>): boolean {
+    // These tools always modify files
+    if (SNAPSHOT_TOOL_NAMES.has(toolName)) {
+      return true;
+    }
+    // For bash commands, inspect the command string for file-modifying patterns
+    if (toolName === 'bash' && input) {
+      const command = typeof input.command === 'string' ? input.command : '';
+      if (!command) {
+        return false;
+      }
+      return FILE_MODIFYING_PATTERNS.some(pattern => pattern.test(command));
+    }
+    return false;
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * Capture a git tree hash using a temporary index file.
+   *
+   * Uses `GIT_INDEX_FILE` to operate on an isolated temporary index so that
+   * the user's real staging area (`.git/index`) is never modified.
+   *
+   * @returns The git tree hash string.
+   * @throws If the git commands fail.
+   */
+  private async captureGitSnapshot(): Promise<string> {
+    // Use a temporary index to avoid corrupting the user's staging area.
+    // GIT_INDEX_FILE tells git to use an alternate index, so `git add -A`
+    // and `git write-tree` operate on the temp file, leaving the real
+    // index (.git/index) untouched.
+    const tmpIndex = path.join(this.projectDir, '.git', `index.nimbus-snapshot-${Date.now()}`);
+    const env = { ...process.env, GIT_INDEX_FILE: tmpIndex };
+    try {
+      await execAsync('git add -A', { cwd: this.projectDir, env });
+      const { stdout } = await execAsync('git write-tree', { cwd: this.projectDir, env });
+      return stdout.trim();
+    } finally {
+      // Clean up the temporary index file
+      try {
+        fs.unlinkSync(tmpIndex);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  /**
+   * Restore the working tree from a git tree hash.
+   *
+   * @param treeHash - The git tree hash to restore.
+   * @throws If the git commands fail.
+   */
+  private async restoreGitSnapshot(treeHash: string): Promise<void> {
+    await execAsync(`git read-tree ${treeHash}`, { cwd: this.projectDir });
+    await execAsync('git checkout-index -a -f', { cwd: this.projectDir });
+  }
+  /**
+   * Copy the current project files into a numbered snapshot directory.
+   * Skips directories listed in SKIP_DIRS.
+   *
+   * @param snapshotId - The snapshot ID used to name the directory.
+   */
+  private async captureFilesystemSnapshot(snapshotId: string): Promise<void> {
+    const destDir = path.join(this.snapshotDir, snapshotId);
+    fs.mkdirSync(destDir, { recursive: true });
+    this.copyDirectoryRecursive(this.projectDir, destDir);
+  }
+  /**
+   * Restore project files from a snapshot directory by copying them back.
+   * Cleans the project directory first (except for SKIP_DIRS and .nimbus)
+   * to ensure deleted files are also restored correctly.
+   *
+   * @param snapshotId - The snapshot ID whose directory to restore from.
+   * @throws If the snapshot directory does not exist.
+   */
+  private async restoreFilesystemSnapshot(snapshotId: string): Promise<void> {
+    const srcDir = path.join(this.snapshotDir, snapshotId);
+    if (!fs.existsSync(srcDir)) {
+      throw new Error(`Snapshot directory not found: ${srcDir}`);
+    }
+    // Remove current project files (excluding skipped directories)
+    this.cleanProjectDirectory();
+    // Copy snapshot files back into the project directory
+    this.copyDirectoryRecursive(srcDir, this.projectDir);
+  }
+  /**
+   * Recursively copy a directory, skipping entries in SKIP_DIRS.
+   * Uses `fs.cpSync` for individual files and recurses into subdirectories.
+   *
+   * @param src - Source directory path.
+   * @param dest - Destination directory path.
+   */
+  private copyDirectoryRecursive(src: string, dest: string): void {
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+      if (SKIP_DIRS.has(entry.name)) {
+        continue;
+      }
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      if (entry.isDirectory()) {
+        fs.mkdirSync(destPath, { recursive: true });
+        this.copyDirectoryRecursive(srcPath, destPath);
+      } else {
+        fs.cpSync(srcPath, destPath);
+      }
+    }
+  }
+  /**
+   * Remove all files and non-skipped directories from the project directory.
+   * This is used before restoring a non-git snapshot to ensure a clean state.
+   */
+  private cleanProjectDirectory(): void {
+    const entries = fs.readdirSync(this.projectDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (SKIP_DIRS.has(entry.name)) {
+        continue;
+      }
+      const fullPath = path.join(this.projectDir, entry.name);
+      try {
+        if (entry.isDirectory()) {
+          fs.rmSync(fullPath, { recursive: true, force: true });
+        } else {
+          fs.unlinkSync(fullPath);
+        }
+      } catch {
+        // Best-effort cleanup; continue on individual file failures
+      }
+    }
+  }
+}