Address initial usage notes to improve DX (#6)

- **Terminology**: Replace all "clone" references with "vlurp" to better reflect that we download tarballs
- **Enhanced default filters**: Now includes `*.md` files (excluding common repo files), `/agents` and `/commands` directories. Refactored to use `glob` for cleaner, more reliable pattern matching
- **Re-vlurping protection**: Warns when overwriting existing directories, shows file count, can bypass with `--force` flag
- **Tree display**: Automatically shows directory structure after vlurping with total file count using ASCII tree. Fixed to show hidden directories like `.claude`
- **Use `glob`**: Avoid reinventing the ~wheel~ `glob`

Author: indexzero

.changeset/friendly-bears-dance.md

@@ -0,0 +1,10 @@
+---
+"vlurp": minor
+---
+
+Improve vlurp user experience based on v1.0.0 feedback:
+
+- **Terminology**: Replace all "clone" references with "vlurp" to better reflect that we download tarballs
+- **Enhanced default filters**: Now includes `*.md` files (excluding common repo files), `/agents` and `/commands` directories. Refactored to use `glob` for cleaner, more reliable pattern matching
+- **Re-vlurping protection**: Warns when overwriting existing directories, shows file count, can bypass with `--force` flag
+- **Tree display**: Automatically shows directory structure after vlurping with total file count using ASCII tree. Fixed to show hidden directories like `.claude`

CONTRIBUTING.md

@@ -5,7 +5,7 @@ Thank you for your interest in contributing to vlurp! This document provides gui
 ## Development
 
 ```sh
-# clone the repository
+# Clone the repository
 git clone git@github.com:indexzero/vlurp.git
 
 # Install dependencies
@@ -124,4 +124,4 @@ Runs on pushes to `main` and handles:
 
 ## Questions?
 
-If you have questions about contributing, feel free to open an issue for discussion.
+If you have questions about contributing, feel free to open an issue for discussion.

README.md

@@ -18,19 +18,19 @@ npx vlurp <user>/<repo>
 ## Usage
 
 ```sh
-# Vlurp a repository using user/repo format
+# vlurp a repository using user/repo format
 vlurp cool-repo/has-agents
 # → Creates ./cool-repo/has-agents
 
-# Vlurp to a specific directory
+# vlurp to a specific directory
 vlurp cool-repo/has-agents -d ~/projects
 # → Creates ~/projects/cool-repo/has-agents
 
-# Vlurp using a GitHub URL
+# vlurp using a GitHub URL
 vlurp https://github.com/whoever/cool-configs
 # → Creates ./whoever/cool-configs
 
-# Vlurp a GitHub Gist
+# vlurp a GitHub Gist
 vlurp https://gist.github.com/user/abc123def456
 # → Creates ./user/abc123def456
 
@@ -40,10 +40,10 @@ vlurp --help
 # Filter files (default: .claude/** and CLAUDE.md)
 vlurp cool-repo/has-agents --filter "*.ts" --filter "*.tsx"
 
-# Vlurp only specific directories
+# vlurp only specific directories
 vlurp whoever/cool-configs --filter "lib/**" --filter "doc/**"
 
-# Vlurp only markdown files
+# vlurp only markdown files
 vlurp user/repo --filter "*.md"
 ```
 

package.json

@@ -8,15 +8,15 @@
     "vlurp": "./bin/vlurp"
   },
   "scripts": {
-    "test": "node --test",
+    "test": "node --test test/*.test.js",
     "lint": "xo",
     "lint:fix": "xo --fix",
     "changeset": "changeset"
   },
   "keywords": [
     "cli",
     "github",
-    "clone",
+    "vlurp",
     "download",
     "fetch",
     "repository",
@@ -29,6 +29,8 @@
   },
   "packageManager": "pnpm@10.14.0",
   "dependencies": {
+    "archy": "^1.0.0",
+    "glob": "^11.0.3",
     "hosted-git-info": "^9.0.0",
     "ink": "^6.1.0",
     "ink-spinner": "^5.0.0",

pnpm-lock.yaml

@@ -10,21 +10,24 @@ const j = jack({
   .description('A fun CLI tool to quickly fetch GitHub repositories and gists')
   .opt({
     d: {
-      description: 'Root directory for cloning',
+      description: 'Root directory for vlurping',
       short: 'd'
     }
   })
   .optList({
     filter: {
-      description: 'Glob patterns to filter files (defaults to .claude/** and CLAUDE.md)',
-      short: 'f',
-      default: ['.claude/**', 'CLAUDE.md']
+      description: 'Glob patterns to filter files (see defaults in help)',
+      default: ['.claude/**', 'CLAUDE.md', '*.md', '!README.md', '!CONTRIBUTING.md', '!LICENSE.md', '!CHANGELOG.md', '!CODE_OF_CONDUCT.md', 'agents/**', 'commands/**']
     }
   })
   .flag({
     help: {
       description: 'Show this help message',
       short: 'h'
+    },
+    force: {
+      description: 'Force overwrite existing directories without prompting',
+      short: 'f'
     }
   });
 
@@ -40,9 +43,10 @@ Usage:
   vlurp <url> -d <root>                 Fetch to <root>/<user>/<repo>
 
 Examples:
-  vlurp facebook/react                   Fetch with default filters (.claude/**, CLAUDE.md)
+  vlurp facebook/react                   Fetch with default filters
   vlurp nodejs/node --filter "*.js"      Fetch only JavaScript files
-  vlurp user/repo -f "src/**" -f "*.md"  Fetch src folder and markdown files
+  vlurp user/repo --filter "src/**"      Fetch src folder
+  vlurp user/repo --force                Force overwrite existing directory
 
 Options:
 ${j.usage()}`);
@@ -57,5 +61,8 @@ if (positionals.length === 0) {
 const source = positionals[0];
 const rootDir = values.d;
 const filters = values.filter;
+const {force} = values;
 
-render(React.createElement(FetchCommand, { source, rootDir, filters }));
+render(React.createElement(FetchCommand, {
+  source, rootDir, filters, force
+}));

src/cli.js

@@ -6,11 +6,13 @@ import Spinner from 'ink-spinner';
 import { parseSource } from '../parser.js';
 import { validateUrl } from '../validator.js';
 import { fetchRepository } from '../fetcher.js';
+import { buildTreeString } from '../tree.js';
 
-export function FetchCommand({ source, rootDir, filters }) {
+export function FetchCommand({ source, rootDir, filters, force }) {
   const [status, setStatus] = useState('locating');
   const [error, setError] = useState(null);
   const [result, setResult] = useState(null);
+  const [treeOutput, setTreeOutput] = useState(null);
 
   useEffect(() => {
     async function performFetch() {
@@ -32,13 +34,18 @@ export function FetchCommand({ source, rootDir, filters }) {
 
         // Vlurp the repository
         setStatus('vlurping');
-        await fetchRepository(parsed.tarballUrl, targetPath, filters);
+        const { fileCount } = await fetchRepository(parsed.tarballUrl, targetPath, filters, { force });
+
+        // Generate tree output
+        const tree = await buildTreeString(targetPath);
+        setTreeOutput(tree);
 
         setResult({
           user: parsed.user,
           repo: parsed.repo,
           path: targetPath,
-          filterCount: filters.length
+          filterCount: filters.length,
+          fileCount
         });
         setStatus('complete');
       } catch (err) {
@@ -48,7 +55,7 @@ export function FetchCommand({ source, rootDir, filters }) {
     }
 
     performFetch();
-  }, [source, rootDir, filters]);
+  }, [source, rootDir, filters, force]);
 
   if (status === 'error') {
     return React.createElement(
@@ -62,9 +69,11 @@ export function FetchCommand({ source, rootDir, filters }) {
     return React.createElement(
       Box,
       { flexDirection: 'column' },
-      React.createElement(Text, { color: 'green' }, `✓ Successfully cloned ${result.user}/${result.repo}`),
+      React.createElement(Text, { color: 'green' }, `✓ Successfully vlurped ${result.user}/${result.repo}`),
       React.createElement(Text, { color: 'gray' }, `  Location: ${result.path}`),
-      result.filterCount > 0 && React.createElement(Text, { color: 'gray' }, `  Filters: ${result.filterCount} pattern(s) applied`)
+      result.filterCount > 0 && React.createElement(Text, { color: 'gray' }, `  Filters: ${result.filterCount} pattern(s) applied`),
+      treeOutput && React.createElement(Box, { marginTop: 1 }, React.createElement(Text, null, treeOutput)),
+      React.createElement(Text, { color: 'cyan', marginTop: 1 }, `✨ vlurped ${result.fileCount} files to ${result.path}`)
     );
   }
 
@@ -76,7 +85,7 @@ export function FetchCommand({ source, rootDir, filters }) {
       null,
       React.createElement(Spinner, { type: 'dots' })
     ),
-    React.createElement(Text, null, ` ${status === 'parsing' ? 'Parsing input...' : 'Cloning repository...'}`)
+    React.createElement(Text, null, ` ${status === 'parsing' ? 'Parsing input...' : 'vlurping repository...'}`)
   );
 }