@prnv/tuck 1.5.0 → 1.5.2

package/README.md

@@ -1,23 +1,30 @@
 <div align="center">
-  <img src="public/tuck.png" alt="tuck logo" width="200">
-</div>
-
-# tuck
-
-> Modern dotfiles manager with a beautiful CLI
+  <img src="public/tuck.png" alt="tuck logo" width="180">
+  
+  # tuck
+  
+  **The modern dotfiles manager**
+  
+  Simple, fast, and beautiful. Manage your dotfiles with Git, sync across machines, and never lose your configs again.
 
 [![npm version](https://img.shields.io/npm/v/@prnv/tuck.svg)](https://www.npmjs.com/package/@prnv/tuck)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/Pranav-Karra-3301/tuck/actions/workflows/ci.yml/badge.svg)](https://github.com/Pranav-Karra-3301/tuck/actions/workflows/ci.yml)
 
-## Features
+[Website](https://tuck.sh) · [Install](#installation) · [Quick Start](#quick-start) · [Commands](#commands)
+
+</div>
+
+---
 
-- **Beautiful CLI** - Gorgeous prompts, spinners, and colors powered by @clack/prompts
-- **Git-native** - Uses git under the hood but abstracts complexity
-- **Organized** - Auto-categorizes your dotfiles (shell, git, editors, terminal, etc.)
-- **Safe** - Never overwrites without confirmation, always creates backups
-- **Fast** - Written in TypeScript, runs on Node.js 18+
-- **Cross-platform** - Works on macOS and Linux
+## Why tuck?
+
+- **One command to rule them all** — `tuck init` scans your system, lets you pick what to track, and syncs to GitHub
+- **Smart detection** — Auto-categorizes dotfiles (shell, git, editors, terminal, ssh, etc.)
+- **Beautiful CLI** — Gorgeous prompts, spinners, and progress bars powered by @clack/prompts
+- **Safe by default** — Creates backups before every operation, never overwrites without asking
+- **Git-native** — Uses Git under the hood but hides the complexity
+- **Cross-platform** — Works on macOS and Linux
 
 ## Installation
 
@@ -25,133 +32,166 @@
 # npm
 npm install -g @prnv/tuck
 
+# Homebrew (macOS/Linux)
+brew install prnv/tap/tuck
+
 # pnpm
 pnpm add -g @prnv/tuck
 
 # yarn
 yarn global add @prnv/tuck
-
-# Homebrew (macOS)
-brew tap pranav-karra-3301/tuck
-brew install tuck
 ```
 
 ## Quick Start
 
+### First time setup
+
 ```bash
-# Initialize tuck (interactive)
+# Interactive setup - scans your system, pick what to track, syncs to GitHub
 tuck init
+```
+
+That's it! `tuck init` does everything:
 
-# Or initialize with a remote repository
-tuck init --from git@github.com:username/dotfiles.git
+1. Creates `~/.tuck` repository
+2. Scans your system for dotfiles
+3. Lets you select which to track
+4. Creates a GitHub repo (optional)
+5. Commits and pushes
 
-# Add your dotfiles
-tuck add ~/.zshrc ~/.gitconfig ~/.config/nvim
+### Ongoing workflow
 
-# Sync changes to repository
+```bash
+# Detect changes, find new dotfiles, commit, and push - all in one
 tuck sync
+```
+
+### On a new machine
 
-# Push to remote
-tuck push
+```bash
+# Apply dotfiles from any GitHub user
+tuck apply username
+
+# Or clone your own and restore
+tuck init --from github.com/you/dotfiles
+tuck restore --all
 ```
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `tuck init` | Initialize tuck repository |
-| `tuck add <paths>` | Track new dotfiles |
-| `tuck remove <paths>` | Stop tracking dotfiles |
-| `tuck sync` | Sync changes to repository |
-| `tuck push` | Push to remote |
+### Essential (what you'll use 99% of the time)
+
+| Command       | Description                                                             |
+| ------------- | ----------------------------------------------------------------------- |
+| `tuck init`   | Set up tuck - scans for dotfiles, select what to track, syncs to GitHub |
+| `tuck sync`   | Detect changes + new files, commit, and push (pulls first if behind)    |
+| `tuck status` | See what's tracked, what's changed, and sync status                     |
+
+### Managing Files
+
+| Command               | Description                        |
+| --------------------- | ---------------------------------- |
+| `tuck add <paths>`    | Manually track specific files      |
+| `tuck remove <paths>` | Stop tracking files                |
+| `tuck scan`           | Discover dotfiles without syncing  |
+| `tuck list`           | List all tracked files by category |
+| `tuck diff [file]`    | Show what's changed                |
+
+### Syncing
+
+| Command     | Description      |
+| ----------- | ---------------- |
+| `tuck push` | Push to remote   |
 | `tuck pull` | Pull from remote |
-| `tuck restore` | Restore dotfiles to system |
-| `tuck status` | Show tracking status |
-| `tuck list` | List tracked files |
-| `tuck diff` | Show changes |
-| `tuck config` | Manage configuration |
+
+### Restoring
+
+| Command             | Description                                            |
+| ------------------- | ------------------------------------------------------ |
+| `tuck apply <user>` | Apply dotfiles from a GitHub user (with smart merging) |
+| `tuck restore`      | Restore dotfiles from repo to system                   |
+| `tuck undo`         | Restore from Time Machine backup snapshots             |
+
+### Configuration
+
+| Command              | Description                     |
+| -------------------- | ------------------------------- |
+| `tuck config`        | View/edit configuration         |
+| `tuck config wizard` | Interactive configuration setup |
 
 ## How It Works
 
-Tuck stores your dotfiles in `~/.tuck` (configurable), organized by category:
+tuck stores your dotfiles in `~/.tuck`, organized by category:
 
 ```
 ~/.tuck/
 ├── files/
-│   ├── shell/      # .zshrc, .bashrc, etc.
+│   ├── shell/      # .zshrc, .bashrc, .profile
 │   ├── git/        # .gitconfig, .gitignore_global
-│   ├── editors/    # .vimrc, nvim config
-│   ├── terminal/   # .tmux.conf, alacritty config
-│   ├── ssh/        # ssh config
+│   ├── editors/    # .vimrc, nvim, VS Code settings
+│   ├── terminal/   # .tmux.conf, alacritty, kitty
+│   ├── ssh/        # ssh config (never keys!)
 │   └── misc/       # everything else
-├── .tuckmanifest.json  # Tracks all managed files
-├── .tuckrc.json        # Tuck configuration
-└── README.md
+├── .tuckmanifest.json
+└── .tuckrc.json
 ```
 
-When you run `tuck add ~/.zshrc`:
-1. The file is copied to `~/.tuck/files/shell/zshrc`
-2. An entry is added to the manifest with the source path and checksum
-3. Run `tuck sync` to commit and `tuck push` to upload
+**The flow:**
 
-When setting up a new machine:
-```bash
-tuck init --from git@github.com:username/dotfiles.git
-tuck restore --all
+```
+~/.zshrc          →  ~/.tuck/files/shell/zshrc
+~/.gitconfig      →  ~/.tuck/files/git/gitconfig
+~/.config/nvim    →  ~/.tuck/files/editors/nvim
 ```
 
+Run `tuck sync` anytime to detect changes and push. On a new machine, run `tuck apply username` to grab anyone's dotfiles.
+
 ## Configuration
 
-Tuck can be configured via `~/.tuck/.tuckrc.json`:
+Configure tuck via `~/.tuck/.tuckrc.json` or `tuck config wizard`:
 
 ```json
 {
   "repository": {
-    "path": "~/.tuck",
-    "defaultBranch": "main",
     "autoCommit": true,
     "autoPush": false
   },
   "files": {
     "strategy": "copy",
-    "backupOnRestore": true,
-    "backupDir": "~/.tuck-backups"
-  },
-  "ui": {
-    "colors": true,
-    "emoji": true,
-    "verbose": false
+    "backupOnRestore": true
   }
 }
 ```
 
 ### File Strategies
 
-- **copy** (default): Files are copied to the repository. Changes in your system don't affect the repo until you run `tuck sync`.
-- **symlink**: Files in your system are replaced with symlinks to the repository. Changes are immediate.
+- **copy** (default) — Files are copied. Run `tuck sync` to update the repo.
+- **symlink** — Files are symlinked. Changes are instant but require more care.
+
+## Security
 
-## Restoring on a New Machine
+tuck is designed with security in mind:
+
+- **Never tracks private keys** — SSH keys, `.env` files, and credentials are blocked by default
+- **Secret scanning** — Warns if files contain API keys or tokens
+- **Placeholder support** — Replace secrets with `{{PLACEHOLDER}}` syntax
+- **Local secrets** — Store actual values in `secrets.local.json` (never committed)
 
 ```bash
-# Option 1: Clone and restore in one step
-tuck init --from git@github.com:username/dotfiles.git
-tuck restore --all
+# Scan tracked files for secrets
+tuck secrets scan
 
-# Option 2: Clone manually
-git clone git@github.com:username/dotfiles.git ~/.tuck
-tuck restore --all
+# Set a secret value locally
+tuck secrets set API_KEY "your-actual-key"
 ```
 
 ## Hooks
 
-Run custom commands before/after sync or restore:
+Run custom commands before/after operations:
 
 ```json
 {
   "hooks": {
-    "preSync": "echo 'About to sync...'",
-    "postSync": "echo 'Sync complete!'",
-    "preRestore": "echo 'Backing up...'",
     "postRestore": "source ~/.zshrc"
   }
 }
@@ -160,26 +200,23 @@ Run custom commands before/after sync or restore:
 ## Development
 
 ```bash
-# Clone the repository
 git clone https://github.com/Pranav-Karra-3301/tuck.git
 cd tuck
-
-# Install dependencies
 pnpm install
-
-# Build
 pnpm build
-
-# Run locally
-node dist/index.js --help
-
-# Run tests
 pnpm test
-
-# Lint
-pnpm lint
 ```
 
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines and submit PRs to the `main` branch.
+
 ## License
 
-MIT - see [LICENSE](LICENSE)
+MIT — see [LICENSE](LICENSE)
+
+---
+
+<div align="center">
+  <sub>Made with love in San Francisco and State College</sub>
+</div>

package/dist/index.js

@@ -8674,6 +8674,7 @@ var listCommand = new Command10("list").description("List all tracked files").op
 
 // src/commands/diff.ts
 init_ui();
+init_theme();
 init_paths();
 init_manifest();
 init_git();
@@ -8701,26 +8702,60 @@ var getFileDiff = async (tuckDir, source) => {
     destination: tracked.file.destination,
     hasChanges: false
   };
-  if (!await pathExists(systemPath)) {
+  const systemExists = await pathExists(systemPath);
+  const repoExists2 = await pathExists(repoPath);
+  if (!systemExists) {
     diff.hasChanges = true;
-    if (await pathExists(repoPath)) {
-      const repoContent = await readFile9(repoPath, "utf-8");
-      diff.repoContent = repoContent;
-      diff.repoSize = repoContent.length;
+    if (repoExists2) {
+      if (await isDirectory(repoPath)) {
+        diff.isDirectory = true;
+        const files = await getDirectoryFiles(repoPath);
+        diff.fileCount = files.length;
+      } else {
+        const repoContent = await readFile9(repoPath, "utf-8");
+        diff.repoContent = repoContent;
+        diff.repoSize = repoContent.length;
+      }
     }
     return diff;
   }
-  if (!await pathExists(repoPath)) {
+  if (!repoExists2) {
     diff.hasChanges = true;
-    const systemContent = await readFile9(systemPath, "utf-8");
-    diff.systemContent = systemContent;
-    diff.systemSize = systemContent.length;
+    if (await isDirectory(systemPath)) {
+      diff.isDirectory = true;
+      const files = await getDirectoryFiles(systemPath);
+      diff.fileCount = files.length;
+    } else {
+      const systemContent = await readFile9(systemPath, "utf-8");
+      diff.systemContent = systemContent;
+      diff.systemSize = systemContent.length;
+    }
+    return diff;
+  }
+  const systemIsDir = await isDirectory(systemPath);
+  const repoIsDir = await isDirectory(repoPath);
+  if (systemIsDir || repoIsDir) {
+    diff.isDirectory = true;
+    if (systemIsDir) {
+      const files = await getDirectoryFiles(systemPath);
+      diff.fileCount = files.length;
+    }
+    if (repoIsDir) {
+      const files = await getDirectoryFiles(repoPath);
+      diff.fileCount = (diff.fileCount || 0) + files.length;
+    }
+    const systemChecksum2 = await getFileChecksum(systemPath);
+    const repoChecksum2 = await getFileChecksum(repoPath);
+    diff.hasChanges = systemChecksum2 !== repoChecksum2;
     return diff;
   }
   const systemIsBinary = await isBinary(systemPath);
   const repoIsBinary = await isBinary(repoPath);
   if (systemIsBinary || repoIsBinary) {
     diff.isBinary = true;
+    const systemChecksum2 = await getFileChecksum(systemPath);
+    const repoChecksum2 = await getFileChecksum(repoPath);
+    diff.hasChanges = systemChecksum2 !== repoChecksum2;
     try {
       const systemBuffer = await readFile9(systemPath);
       diff.systemSize = systemBuffer.length;
@@ -8731,24 +8766,6 @@ var getFileDiff = async (tuckDir, source) => {
       diff.repoSize = repoBuffer.length;
     } catch {
     }
-    const systemChecksum2 = await getFileChecksum(systemPath);
-    const repoChecksum2 = await getFileChecksum(repoPath);
-    diff.hasChanges = systemChecksum2 !== repoChecksum2;
-    return diff;
-  }
-  const systemIsDir = await isDirectory(systemPath);
-  const repoIsDir = await isDirectory(repoPath);
-  if (systemIsDir || repoIsDir) {
-    diff.isDirectory = true;
-    diff.hasChanges = true;
-    if (systemIsDir) {
-      const files = await getDirectoryFiles(systemPath);
-      diff.fileCount = files.length;
-    }
-    if (repoIsDir) {
-      const files = await getDirectoryFiles(repoPath);
-      diff.fileCount = (diff.fileCount || 0) + files.length;
-    }
     return diff;
   }
   try {
@@ -8786,26 +8803,27 @@ var formatUnifiedDiff = (diff) => {
     return lines.join("\n");
   }
   const { systemContent, repoContent } = diff;
-  if (!systemContent && repoContent) {
+  const systemMissing = systemContent === void 0;
+  const repoMissing = repoContent === void 0;
+  if (systemMissing && !repoMissing) {
     lines.push(colors.red("File missing on system"));
     lines.push(colors.dim("Repository content:"));
     repoContent.split("\n").forEach((line) => {
       lines.push(colors.green(`+ ${line}`));
     });
-  } else if (systemContent && !repoContent) {
+  } else if (!systemMissing && repoMissing) {
     lines.push(colors.yellow("File not yet synced to repository"));
     lines.push(colors.dim("System content:"));
     systemContent.split("\n").forEach((line) => {
       lines.push(colors.red(`- ${line}`));
     });
-  } else if (systemContent && repoContent) {
+  } else if (!systemMissing && !repoMissing) {
     const CONTEXT_LINES = 3;
     const systemLines = systemContent.split("\n");
     const repoLines = repoContent.split("\n");
     const maxLines = Math.max(systemLines.length, repoLines.length);
     let inDiff = false;
     let diffStart = 0;
-    let contextCount = 0;
     for (let i = 0; i < maxLines; i++) {
       const sysLine = systemLines[i];
       const repoLine = repoLines[i];
@@ -8814,12 +8832,19 @@ var formatUnifiedDiff = (diff) => {
           inDiff = true;
           diffStart = i;
           const startLine = Math.max(0, diffStart - CONTEXT_LINES + 1);
-          const endLine = Math.min(maxLines, diffStart + CONTEXT_LINES);
+          const contextLineCount = Math.min(diffStart, CONTEXT_LINES);
+          const endLine = Math.min(maxLines, diffStart + CONTEXT_LINES + 1);
           lines.push(
             colors.cyan(
-              `@@ -${startLine + 1},${endLine - startLine} +${startLine + 1},${endLine - startLine} @@`
+              `@@ -${startLine + 1},${contextLineCount + 1} +${startLine + 1},${endLine - startLine} @@`
             )
           );
+          for (let j = startLine; j < i; j++) {
+            const ctxLine = systemLines[j];
+            if (ctxLine !== void 0) {
+              lines.push(colors.dim(`  ${ctxLine}`));
+            }
+          }
         }
         if (sysLine !== void 0) {
           lines.push(colors.red(`- ${sysLine}`));
@@ -8827,13 +8852,12 @@ var formatUnifiedDiff = (diff) => {
         if (repoLine !== void 0) {
           lines.push(colors.green(`+ ${repoLine}`));
         }
-        contextCount = 0;
       } else if (inDiff) {
-        lines.push(colors.dim(`  ${sysLine || ""}`));
-        contextCount++;
-        if (contextCount > CONTEXT_LINES * 2) {
-          inDiff = false;
+        if (sysLine === repoLine && sysLine !== void 0) {
+          lines.push(colors.dim(`  ${sysLine}`));
         }
+      } else {
+        inDiff = false;
       }
     }
   }
@@ -10706,10 +10730,7 @@ init_git();
 var program = new Command16();
 program.name("tuck").description(DESCRIPTION).version(VERSION, "-v, --version", "Display version number").configureOutput({
   outputError: (str, write) => write(chalk5.red(str))
-}).addHelpText("beforeAll", customHelp(VERSION)).helpOption("-h, --help", "Display this help message").showHelpAfterError(false);
-program.configureHelp({
-  formatHelp: () => ""
-});
+}).addHelpText("before", customHelp(VERSION)).helpOption("-h, --help", "Display this help message").showHelpAfterError(false);
 program.addCommand(initCommand);
 program.addCommand(addCommand);
 program.addCommand(removeCommand);
@@ -10778,9 +10799,7 @@ var runDefaultAction = async () => {
     console.log();
   }
 };
-var hasCommand = process.argv.slice(2).some(
-  (arg) => !arg.startsWith("-") && arg !== "--help" && arg !== "-h"
-);
+var hasCommand = process.argv.slice(2).some((arg) => !arg.startsWith("-") && arg !== "--help" && arg !== "-h");
 process.on("uncaughtException", handleError);
 process.on("unhandledRejection", (reason) => {
   handleError(reason instanceof Error ? reason : new Error(String(reason)));