craftvault 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CraftVault Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,353 @@
-# Temporary Holding Version
+# 🛠️ CraftVault
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A local-first, high-performance Version Control System with Git-like workflow and beautiful web UI**
+
+Built from scratch with content-addressable storage, real-time updates, and zero configuration needed.
+
+[![Tests](https://img.shields.io/badge/tests-146%2B%20passing-brightgreen)]()
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)]()
+[![React](https://img.shields.io/badge/React-18.2-61dafb)]()
+[![License](https://img.shields.io/badge/license-MIT-green)]()
+
+---
+
+## ✨ Features
+
+- 🚀 **Git-like Commands** - Familiar workflow: `init`, `add`, `commit`, `log`, `diff`, `branch`
+- 🎨 **Beautiful Web UI** - Modern React interface with real-time updates
+- 📦 **Content-Addressable Storage** - Efficient deduplication using SHA-1 hashing
+- ⚡ **Real-Time Updates** - WebSocket-powered live status and commit tracking
+- 🔍 **Smart Diff Engine** - Myers algorithm for accurate file comparisons
+- 📁 **.cvignore Support** - Gitignore-style pattern matching
+- 🌳 **Branch Management** - Create and switch between branches
+- 🔌 **REST API** - Complete HTTP API for integrations
+- 🎯 **Zero Configuration** - Works out of the box
+
+---
+
+## 🚀 Quick Start
+
+### Installation (Choose One)
+
+**Option 1: Global Install (Recommended)**
+```bash
+npm install -g craftvault
+```
+
+**Option 2: Use with npx (No Installation)**
+```bash
+npx craftvault init
+```
+
+**Option 3: Local Project**
+```bash
+npm install craftvault
+npx cv init
+```
+
+### 60-Second Demo
+
+```bash
+# 1. Create a project and initialize
+mkdir my-project && cd my-project
+cv init
+
+# 2. Create some files
+echo "console.log('Hello');" > app.js
+echo "body { margin: 0; }" > style.css
+
+# 3. Track and commit
+cv add .
+cv commit -m "Initial commit"
+
+# 4. Launch the UI
+cv ui
+```
+
+**That's it!** Your browser will open automatically at `http://localhost:3000` showing your commits and changes.
+
+---
+
+## 📖 Basic Commands
+
+```bash
+cv init                          # Initialize repository
+cv status                        # Show file status
+cv add <files...>               # Stage files
+cv commit -m "message"          # Create commit
+cv log [--oneline]              # View history
+cv diff <file>                  # Show changes
+cv branch [name]                # Manage branches
+cv ui                           # Launch web interface 🌐
+```
+
+---
+
+## 🌐 Web UI
+
+Run `cv ui` to launch the interface:
+
+- 📊 Visual commit history with timestamps
+- 📝 Color-coded file diffs (added/removed/modified)
+- ✅ Staged vs unstaged files with one-click actions
+- 🔄 Real-time auto-updates as you make changes
+- 🎨 GitHub-like interface that's familiar and intuitive
+
+**How it works:**
+- Backend server runs on port 3000 (configurable)
+- Browser opens automatically
+- WebSocket keeps everything in sync
+- Press `Ctrl+C` to stop
+
+---
+
+## 📂 .cvignore
+
+Automatically created on `cv init` with sensible defaults:
+
+```gitignore
+# .cvignore (uses gitignore syntax)
+node_modules/
+dist/
+*.log
+.env
+```
+
+Works exactly like `.gitignore` - add patterns to exclude files from tracking.
+
+---
+
+## 🔄 Complete Workflow Example
+
+```bash
+# Initialize in your project
+cd ~/my-awesome-app
+cv init
+
+# Make some changes
+echo "const app = 'Hello';" > app.js
+mkdir src
+echo "export const utils = {};" > src/utils.js
+
+# Check status
+cv status
+
+# Stage specific files
+cv add app.js src/utils.js
+
+# Or stage everything
+cv add .
+
+# Create commit
+cv commit -m "Add initial structure"
+
+# View history
+cv log
+cv log --oneline
+
+# Make more changes
+echo "// Updated" >> app.js
+
+# See what changed
+cv diff app.js
+
+# Launch UI to visualize everything
+cv ui
+```
+
+---
+
+## 🆚 CraftVault vs Git
+
+| Feature | CraftVault | Git |
+|---------|-----------|-----|
+| **Initialization** | `cv init` | `git init` |
+| **Stage Files** | `cv add .` | `git add .` |
+| **Commit** | `cv commit -m "msg"` | `git commit -m "msg"` |
+| **View History** | `cv log` | `git log` |
+| **See Changes** | `cv diff file` | `git diff file` |
+| **Web UI** | `cv ui` ✨ Built-in | Requires external tools |
+| **Real-time Updates** | ✅ WebSocket | ❌ Not available |
+| **Learning Curve** | 🟢 Minimal | 🟡 Moderate |
+| **Remote Push/Pull** | 🟡 Coming soon | ✅ Yes |
+
+---
+
+## 🏗️ Architecture
+
+CraftVault uses a content-addressable storage model similar to Git:
+
+- **Blobs** - Store file contents
+- **Trees** - Store directory structure
+- **Commits** - Store snapshots with metadata
+- **Refs** - Store branch pointers
+
+**Storage:**
+```
+.cv/
+├── objects/          # All Git objects (blobs, trees, commits)
+│   └── ab/          # First 2 chars of SHA-1
+│       └── cdef...  # Remaining 38 chars
+├── refs/
+│   └── heads/       # Branch references
+│       └── main
+├── HEAD             # Current branch pointer
+└── index            # Staging area
+```
+
+---
+
+## 📚 Documentation
+
+### Quick Guides
+- **[Simple Install Guide](./SIMPLE_INSTALL.md)** - Get started in 2 minutes
+- **[Quick Start Guide](./QUICK_START.md)** - Essential commands
+
+### Comprehensive Docs
+- **[Architecture](./ARCHITECTURE.md)** - System design and implementation (4,500 words)
+- **[API Reference](./API.md)** - REST API documentation (3,000 words)
+- **[User Guide](./USER_GUIDE.md)** - Complete command reference (3,500 words)
+- **[Contributing](./CONTRIBUTING.md)** - Developer guidelines (2,500 words)
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run integration tests
+node test-integration.js
+
+# Results: 146+ tests, 100% pass rate
+```
+
+Test coverage:
+- Repository initialization
+- File tracking and staging
+- Commit creation and history
+- Branch management
+- Diff computation
+- CLI commands
+- API endpoints
+
+---
+
+## 🛠️ Development
+
+### Build from Source
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd craftvault
+
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Build UI
+cd ui && npm install && npm run build && cd ..
+
+# Link globally for development
+npm link
+
+# Now use cv from anywhere
+cv --version
+```
+
+### Project Structure
+
+```
+craftvault/
+├── src/
+│   ├── core/              # Core VCS functionality
+│   │   ├── blob.ts        # File content storage
+│   │   ├── tree.ts        # Directory structure
+│   │   ├── commit.ts      # Commit objects
+│   │   ├── repository.ts  # Repo management
+│   │   ├── storage.ts     # Object storage
+│   │   ├── diff-engine.ts # Myers diff algorithm
+│   │   └── ...
+│   ├── cli/               # Command-line interface
+│   │   └── commands/      # Individual commands
+│   ├── api/               # REST API + WebSocket
+│   │   └── server.ts      # Hono server
+│   └── utils/             # Hash, compression, diff, ignore
+├── ui/                    # React web interface
+│   └── src/
+│       ├── components/    # UI components
+│       └── App.jsx        # Main application
+├── dist/                  # Compiled TypeScript
+└── docs/                  # Documentation
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+**Ways to contribute:**
+- 🐛 Report bugs
+- 💡 Suggest features
+- 📝 Improve documentation
+- 🔧 Submit pull requests
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](./LICENSE) for details.
+
+---
+
+## 🎓 Learning Resources
+
+### For Users
+- Start with [SIMPLE_INSTALL.md](./SIMPLE_INSTALL.md)
+- Try the 60-second demo above
+- Run `cv --help` for command list
+- Launch `cv ui` to explore visually
+
+### For Developers
+- Read [ARCHITECTURE.md](./ARCHITECTURE.md) for system design
+- Check [API.md](./API.md) for API integration
+- See [CONTRIBUTING.md](./CONTRIBUTING.md) for dev setup
+
+---
+
+## 🌟 Highlights
+
+**What makes CraftVault special:**
+
+1. **Complete Implementation** - Not a toy project. Fully functional VCS with 15,000+ lines of TypeScript
+2. **Modern Stack** - TypeScript, React 18, Hono v4, WebSocket
+3. **Production-Ready** - Comprehensive testing, error handling, documentation
+4. **Educational** - Clear code, detailed architecture docs, great for learning
+5. **User-Friendly** - Beautiful UI, sensible defaults, zero configuration
+
+---
+
+## 🚀 What's Next?
+
+**Planned Features:**
+- Remote repository support (push/pull)
+- Merge conflict resolution UI
+- Performance optimizations for large repos
+- Plugin system
+- VS Code extension
+
+---
+
+## 💬 Support
+
+- 📖 Check the [documentation](./ARCHITECTURE.md)
+- 🐛 [Report issues](https://github.com/yourusername/craftvault/issues)
+- 💡 [Request features](https://github.com/yourusername/craftvault/issues/new)
+
+---
+
+**Built with ❤️ by the CraftVault team**
+
+*Making version control simple, visual, and delightful*

package/dist/.cv/HEAD

@@ -0,0 +1 @@
+ref: refs/heads/main

package/dist/.cv/index

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "entries": {}
+}

package/dist/api/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * API Module Exports
+ */
+export * from './server';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC"}

package/dist/api/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * API Module Exports
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./server"), exports);
+__exportStar(require("./types"), exports);
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;AAEH,2CAAyB;AACzB,0CAAwB"}

package/dist/api/server.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Core Engine Server
+ * REST API with WebSocket support using Hono
+ */
+export interface ServerOptions {
+    repoPath: string;
+    port?: number;
+    host?: string;
+}
+export declare class CraftVaultServer {
+    private app;
+    private repoPath;
+    private port;
+    private host;
+    private wss;
+    private watcher;
+    private clients;
+    private repo;
+    private statusComputer;
+    private addCommand;
+    private commitBuilder;
+    private commitHistory;
+    private diffEngine;
+    private refManager;
+    private server;
+    constructor(options: ServerOptions);
+    private setupMiddleware;
+    private setupRoutes;
+    private setupStaticFileServing;
+    private setupWebSocket;
+    private setupFileWatcher;
+    private sendStatus;
+    private broadcast;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/api/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/api/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA8BH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,GAAG,CAAO;IAClB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,GAAG,CAAgC;IAC3C,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,OAAO,CAA6B;IAG5C,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAa;IAE/B,OAAO,CAAC,MAAM,CAAa;gBAEf,OAAO,EAAE,aAAa;IAmBlC,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,WAAW;IAyPnB,OAAO,CAAC,sBAAsB;IA2C9B,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,gBAAgB;YAkBV,UAAU;IAqBxB,OAAO,CAAC,SAAS;IASX,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAe5B"}