feat(time-machine): auto-capture initial snapshot when project is added

When a project is added to PackageFlow, automatically capture an initial
snapshot if a lockfile exists. This enables proper dependency change
tracking when users later add/remove packages.

Author: runkids

README.md

@@ -35,15 +35,10 @@
   <a href="#-faq"><strong>❓ FAQ</strong></a>
 </p>
 
-<p align="center">
-  <a href="./README.zh-TW.md">繁體中文</a> •
-  <a href="./README.zh-CN.md">简体中文</a>
-</p>
-
 ---
 
 <p align="center">
-  <img src="docs/screenshots/deploy-demo.gif" width="720" alt="PackageFlow Hero" />
+  <img src="docs/screenshots/chat-with-ai.gif" width="720" alt="PackageFlow Hero" />
 </p>
 
 <!-- TODO: Add a 20–40s product demo video link (YouTube/X) and/or a thumbnail image here. -->

README.zh-CN.md

@@ -92,7 +92,7 @@ PackageFlow 是「AI 驱动」的意思不是只会聊天，而是 AI 可以调
 </p>
 
 <p align="center">
-  <img src="docs/screenshots/deploy-demo.gif" width="720" alt="Deploy demo" />
+  <img src="docs/screenshots/chat-with-ai.gif" width="720" alt="Deploy demo" />
   <br/>
   <em>👆 一键部署，即时获取预览链接</em>
 </p>

README.zh-TW.md

@@ -92,7 +92,7 @@ PackageFlow 是「AI 驅動」的意思不是只會聊天，而是 AI 可以呼
 </p>
 
 <p align="center">
-  <img src="docs/screenshots/deploy-demo.gif" width="720" alt="Deploy demo" />
+  <img src="docs/screenshots/chat-with-ai.gif" width="720" alt="Deploy demo" />
   <br/>
   <em>👆 一鍵部署，即時取得預覽連結</em>
 </p>

docs/screenshots/chat-with-ai.gif

@@ -9,8 +9,8 @@
     "dev:tauri": "tauri dev",
     "build": "tsc && vite build",
     "build:tauri": "tauri build --bundles dmg",
-    "build:mcp": "cargo build --manifest-path src-tauri/Cargo.toml --bin packageflow-mcp && node scripts/ensure-mcp-alias.mjs --profile=debug",
-    "build:mcp:release": "cargo build --manifest-path src-tauri/Cargo.toml --release --bin packageflow-mcp && node scripts/ensure-mcp-alias.mjs --profile=release",
+    "build:mcp": "mkdir -p src-tauri/target/debug && touch src-tauri/target/debug/packageflow-mcp && cargo build --manifest-path src-tauri/Cargo.toml --bin packageflow-mcp && node scripts/ensure-mcp-alias.mjs --profile=debug",
+    "build:mcp:release": "mkdir -p src-tauri/target/release && touch src-tauri/target/release/packageflow-mcp && cargo build --manifest-path src-tauri/Cargo.toml --release --bin packageflow-mcp && node scripts/ensure-mcp-alias.mjs --profile=release",
     "prebuild:tauri": "pnpm test:mcp && pnpm build:mcp:release",
     "predev:tauri": "pkill -f packageflow-mcp || true; pnpm build:mcp",
     "preview": "vite preview",

package.json

@@ -6,11 +6,13 @@ use chrono::Utc;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::fs;
-use std::path::Path;
+use std::path::{Path, PathBuf};
 use uuid::Uuid;
 
+use crate::models::snapshot::TriggerSource;
 use crate::models::{PackageManager, Project, WorkspacePackage};
 use crate::repositories::ProjectRepository;
+use crate::services::snapshot::{SnapshotCaptureService, SnapshotStorage};
 use crate::DatabaseState;
 
 /// Response for scan_project command
@@ -308,14 +310,97 @@ pub async fn scan_project(
     })
 }
 
+/// Get the snapshot storage base path
+fn get_storage_base_path() -> Result<PathBuf, String> {
+    dirs::data_dir()
+        .map(|p| p.join("com.packageflow.app").join("time-machine"))
+        .ok_or_else(|| "Failed to get data directory".to_string())
+}
+
 /// Save a project to SQLite database
+/// Also captures an initial snapshot if the project has a lockfile
 #[tauri::command]
 pub async fn save_project(
     db: tauri::State<'_, DatabaseState>,
     project: Project,
 ) -> Result<(), String> {
     let repo = ProjectRepository::new(db.0.as_ref().clone());
-    repo.save(&project)
+    repo.save(&project)?;
+
+    // Capture initial snapshot in background
+    let project_path = project.path.clone();
+    let db_clone = db.0.as_ref().clone();
+
+    // Spawn a background task to capture initial snapshot
+    tokio::spawn(async move {
+        if let Err(e) = capture_initial_snapshot(&project_path, db_clone).await {
+            log::warn!(
+                "[project] Failed to capture initial snapshot for {}: {}",
+                project_path,
+                e
+            );
+        }
+    });
+
+    Ok(())
+}
+
+/// Capture initial snapshot for a newly added project
+async fn capture_initial_snapshot(
+    project_path: &str,
+    db: crate::utils::database::Database,
+) -> Result<(), String> {
+    let path = Path::new(project_path);
+
+    // Check if project has a lockfile
+    let has_lockfile = path.join("pnpm-lock.yaml").exists()
+        || path.join("package-lock.json").exists()
+        || path.join("yarn.lock").exists()
+        || path.join("bun.lockb").exists();
+
+    if !has_lockfile {
+        log::info!(
+            "[project] No lockfile found for {}, skipping initial snapshot",
+            project_path
+        );
+        return Ok(());
+    }
+
+    let base_path = get_storage_base_path()?;
+    let project_path_owned = project_path.to_string();
+
+    // Run in blocking task since snapshot capture involves file I/O
+    tokio::task::spawn_blocking(move || {
+        let storage = SnapshotStorage::new(base_path);
+        let service = SnapshotCaptureService::new(storage, db);
+
+        let request = crate::models::snapshot::CreateSnapshotRequest {
+            project_path: project_path_owned.clone(),
+            trigger_source: TriggerSource::Manual, // Initial snapshot
+        };
+
+        match service.capture_snapshot(&request) {
+            Ok(snapshot) => {
+                log::info!(
+                    "[project] Captured initial snapshot {} for project {} ({} dependencies)",
+                    snapshot.id,
+                    project_path_owned,
+                    snapshot.total_dependencies
+                );
+                Ok(())
+            }
+            Err(e) => {
+                log::error!(
+                    "[project] Failed to capture initial snapshot for {}: {}",
+                    project_path_owned,
+                    e
+                );
+                Err(e)
+            }
+        }
+    })
+    .await
+    .map_err(|e| format!("Task join error: {}", e))?
 }
 
 /// Remove a project from SQLite database

src-tauri/src/commands/project.rs

@@ -16,7 +16,7 @@ import {
   Search,
 } from 'lucide-react';
 import { type RunningScript } from '../../hooks/useScriptExecution';
-import { useTerminalHeight } from '../../hooks/useTerminalHeight';
+import { useSettings } from '../../contexts/SettingsContext';
 import { useTerminalSearch, highlightSearchMatches } from '../../hooks/useTerminalSearch';
 import AnsiToHtml from 'ansi-to-html';
 
@@ -90,7 +90,29 @@ export function ScriptTerminal({
   const startYRef = useRef(0);
   const startHeightRef = useRef(0);
 
-  const { height, updateHeight, MIN_HEIGHT, MAX_HEIGHT } = useTerminalHeight();
+  const { terminalHeight: height, setTerminalHeight } = useSettings();
+  const MIN_HEIGHT = 100;
+  const MAX_HEIGHT = 600;
+
+  // Debounce height updates to avoid excessive DB writes
+  const updateHeightTimeoutRef = useRef<number | undefined>(undefined);
+  const updateHeight = useCallback((newHeight: number) => {
+    if (updateHeightTimeoutRef.current) {
+      clearTimeout(updateHeightTimeoutRef.current);
+    }
+    updateHeightTimeoutRef.current = window.setTimeout(() => {
+      setTerminalHeight(newHeight);
+    }, 500);
+  }, [setTerminalHeight]);
+
+  // Cleanup timeout on unmount
+  useEffect(() => {
+    return () => {
+      if (updateHeightTimeoutRef.current) {
+        clearTimeout(updateHeightTimeoutRef.current);
+      }
+    };
+  }, []);
 
   const activeScript = activeExecutionId ? runningScripts.get(activeExecutionId) : null;
 

src/components/project/ScriptTerminal.tsx

@@ -30,7 +30,6 @@ import {
   Trash2,
   Terminal as TerminalIcon,
 } from 'lucide-react';
-import { useTerminalHeight } from '../../hooks/useTerminalHeight';
 import { scriptAPI } from '../../lib/tauri-api';
 import { useSettings } from '../../contexts/SettingsContext';
 import { Button } from '../ui/Button';
@@ -171,8 +170,30 @@ export const ScriptPtyTerminal = forwardRef<ScriptPtyTerminalRef, ScriptPtyTermi
     const startYRef = useRef(0);
     const startHeightRef = useRef(0);
 
-    // Settings context for path formatting
-    const { formatPath } = useSettings();
+    // Settings context for path formatting and terminal height
+    const { formatPath, terminalHeight: height, setTerminalHeight } = useSettings();
+    const MIN_HEIGHT = 100;
+    const MAX_HEIGHT = 600;
+
+    // Debounce height updates to avoid excessive DB writes
+    const updateHeightTimeoutRef = useRef<number | undefined>(undefined);
+    const updateHeight = useCallback((newHeight: number) => {
+      if (updateHeightTimeoutRef.current) {
+        clearTimeout(updateHeightTimeoutRef.current);
+      }
+      updateHeightTimeoutRef.current = window.setTimeout(() => {
+        setTerminalHeight(newHeight);
+      }, 500);
+    }, [setTerminalHeight]);
+
+    // Cleanup height update timeout on unmount
+    useEffect(() => {
+      return () => {
+        if (updateHeightTimeoutRef.current) {
+          clearTimeout(updateHeightTimeoutRef.current);
+        }
+      };
+    }, []);
 
     // Feature 008: Store callback refs to avoid stale closures in useEffect
     const onUpdatePtyOutputRef = useRef(onUpdatePtyOutput);
@@ -182,9 +203,6 @@ export const ScriptPtyTerminal = forwardRef<ScriptPtyTerminalRef, ScriptPtyTermi
       onUpdatePtyStatusRef.current = onUpdatePtyStatus;
     }, [onUpdatePtyOutput, onUpdatePtyStatus]);
 
-    // Use persisted height hook
-    const { height, updateHeight, MIN_HEIGHT, MAX_HEIGHT } = useTerminalHeight();
-
     // Get active session
     const activeSession = activeSessionId ? sessions.get(activeSessionId) : null;
 

src/components/terminal/ScriptPtyTerminal.tsx

@@ -166,7 +166,7 @@ export function SnapshotDetailPanel({
   ];
 
   return (
-    <div className={cn('flex h-full -m-4 animate-in fade-in-0 duration-200', className)}>
+    <div className={cn('flex -m-4 animate-in fade-in-0 duration-200', className)}>
       {/* Left Sidebar Navigation */}
       <div className="w-56 flex-shrink-0 bg-card rounded-lg overflow-hidden m-4 mr-0 self-start">
         <div className="p-3 border-b border-border">
@@ -225,14 +225,14 @@ export function SnapshotDetailPanel({
       </div>
 
       {/* Right Content Area */}
-      <div className="flex-1 min-w-0 overflow-hidden p-4 flex flex-col">
+      <div className="flex-1 min-w-0 p-4">
         {/* Overview Tab */}
-        <div className={cn('flex-1 overflow-y-auto', activeTab !== 'overview' && 'hidden')}>
+        <div className={cn(activeTab !== 'overview' && 'hidden')}>
           <OverviewTabContent snapshot={snapshot} />
         </div>
 
         {/* Dependencies Tab */}
-        <div className={cn('flex-1 overflow-y-auto', activeTab !== 'dependencies' && 'hidden')}>
+        <div className={cn(activeTab !== 'dependencies' && 'hidden')}>
           <DependenciesTabContent
             dependencies={dependencies}
             loading={loading}
@@ -252,12 +252,12 @@ export function SnapshotDetailPanel({
         </div>
 
         {/* Integrity Tab */}
-        <div className={cn('flex-1 overflow-y-auto', activeTab !== 'integrity' && 'hidden')}>
+        <div className={cn(activeTab !== 'integrity' && 'hidden')}>
           <IntegrityTabContent snapshot={snapshot} />
         </div>
 
         {/* Compare Tab */}
-        <div className={cn('flex-1 overflow-y-auto', activeTab !== 'compare' && 'hidden')}>
+        <div className={cn(activeTab !== 'compare' && 'hidden')}>
           <CompareTabContent
             currentSnapshotId={snapshot.id}
             allSnapshots={allSnapshots}
@@ -293,33 +293,23 @@ function OverviewTabContent({ snapshot }: { snapshot: ExecutionSnapshot }) {
       <div>
         <h2 className="text-lg font-semibold text-foreground">Snapshot Overview</h2>
         <p className="text-sm text-muted-foreground mt-1">
-          {snapshot.triggerSource === 'manual' ? 'Manual capture' : 'Auto-captured on lockfile change'}
+          {snapshot.triggerSource === 'manual'
+            ? 'Manual capture'
+            : 'Auto-captured on lockfile change'}
         </p>
       </div>
 
       {/* Stats Grid */}
       <div className="grid grid-cols-2 gap-4">
-        <StatCard
-          icon={Clock}
-          label="Created"
-          value={formatDate(snapshot.createdAt)}
-        />
+        <StatCard icon={Clock} label="Created" value={formatDate(snapshot.createdAt)} />
         <StatCard
           icon={Package}
           label="Package Manager"
           value={(snapshot.lockfileType || 'Unknown').toUpperCase()}
         />
-        <StatCard
-          icon={HardDrive}
-          label="Storage"
-          value={formatSize(snapshot.compressedSize)}
-        />
+        <StatCard icon={HardDrive} label="Storage" value={formatSize(snapshot.compressedSize)} />
         <div
-          className={cn(
-            'p-4 rounded-xl',
-            'bg-card border border-border',
-            'flex items-start gap-3'
-          )}
+          className={cn('p-4 rounded-xl', 'bg-card border border-border', 'flex items-start gap-3')}
         >
           <div className="flex-shrink-0 w-10 h-10 rounded-lg bg-cyan-500/10 flex items-center justify-center">
             <Shield className="w-5 h-5 text-cyan-500" />
@@ -384,13 +374,7 @@ function StatCard({
   value: string;
 }) {
   return (
-    <div
-      className={cn(
-        'p-4 rounded-xl',
-        'bg-card border border-border',
-        'flex items-start gap-3'
-      )}
-    >
+    <div className={cn('p-4 rounded-xl', 'bg-card border border-border', 'flex items-start gap-3')}>
       <div className="flex-shrink-0 w-10 h-10 rounded-lg bg-cyan-500/10 flex items-center justify-center">
         <Icon className="w-5 h-5 text-cyan-500" />
       </div>
@@ -479,11 +463,7 @@ function DependenciesTabContent({
           active={showDirect}
           onClick={() => onShowDirectChange(!showDirect)}
         />
-        <FilterPill
-          label="Dev"
-          active={showDev}
-          onClick={() => onShowDevChange(!showDev)}
-        />
+        <FilterPill label="Dev" active={showDev} onClick={() => onShowDevChange(!showDev)} />
         <FilterPill
           label="Postinstall"
           active={showPostinstall}
@@ -511,9 +491,7 @@ function DependenciesTabContent({
           {directDeps.length > 0 && (
             <DependencyGroup title="Direct" deps={directDeps} variant="primary" />
           )}
-          {devDeps.length > 0 && (
-            <DependencyGroup title="Dev" deps={devDeps} variant="secondary" />
-          )}
+          {devDeps.length > 0 && <DependencyGroup title="Dev" deps={devDeps} variant="secondary" />}
           {transitiveDeps.length > 0 && (
             <DependencyGroup title="Transitive" deps={transitiveDeps} variant="muted" />
           )}