@harpiaresearch/vref 1.0.1 → 1.0.2

package/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2024, Harpia AI Research
+Copyright (c) 2026, Harpia AI Research
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

package/README.md

@@ -146,14 +146,16 @@ npx @harpiaresearch/vref
 
 **CLI:**
 ```bash
-# From a directory
+# From a directory (via npx or global/local vref)
 npx @harpiaresearch/vref ./my-images -o references.vref
 
-# With metadata
+# With metadata (including title name)
 npx @harpiaresearch/vref ./images -o pack.vref \
   -n "My Reference Pack" \
   -d "Collection of art references" \
-  -t "art,style,inspiration"
+  -t "art,style,inspiration" \
+  -a "Your Name" \
+  -l "CC-BY-4.0"
 ```
 
 **Code:**
@@ -161,22 +163,40 @@ npx @harpiaresearch/vref ./images -o pack.vref \
 import { VREFWriter } from '@harpiaresearch/vref';
 
 const writer = new VREFWriter({
-  fileName: 'references.vref',
-  description: 'Art style references',
+  name: 'Art Style References',
+  description: 'Collection of curated art style references',
   tags: ['art', 'style'],
+  author: 'Your Name',
+  license: 'CC-BY-4.0',
 });
 
 writer.addImagesFromDirectory('./images');
 writer.write('references.vref');
 ```
 
+### Inspecting, Validating & Extracting via CLI
+
+```bash
+# Inspect metadata and images in a pack
+vref info references.vref
+
+# Validate format and manifest integrity
+vref validate references.vref
+
+# Extract images to a directory
+vref extract references.vref ./extracted-images
+```
+
 ### Reading a .vref File
 
 ```typescript
 import { VREFReader } from '@harpiaresearch/vref';
 
-// Read file
-const vref = VREFReader.read('references.vref', { loadImages: true });
+// Read file (optional validation & preloading)
+const vref = VREFReader.read('references.vref', {
+  validate: true,
+  loadImages: true,
+});
 
 console.log(`Loaded ${vref.manifest.imageCount} images`);
 
@@ -185,6 +205,9 @@ const randomSamples = vref.sample(3);
 
 // Get specific image
 const image = vref.getImage('photo1.png');
+
+// Extract all images to disk
+VREFReader.extract('references.vref', './extracted');
 ```
 
 ---
@@ -243,7 +266,7 @@ references.vref
 
 ```json
 {
-  "version": "1.0.0",
+  "version": "1.0.2",
   "format": "VREF",
   "fileName": "references.vref",
   "imageCount": 24,
@@ -256,8 +279,9 @@ references.vref
       "height": 1080
     }
   ],
-  "createdAt": "2024-10-12T10:30:00.000Z",
+  "createdAt": "2026-10-13T10:30:00.000Z",
   "metadata": {
+    "name": "RPG Sprites",
     "description": "Collection of references",
     "tags": ["style", "mood"],
     "author": "Your Name",
@@ -286,8 +310,9 @@ No company owns it. Community-driven. Free forever.
 ### 📦 Already Shipping
 - ✅ npm package published
 - ✅ Full TypeScript support
-- ✅ CLI tool ready
-- ✅ Documentation complete
+- ✅ CLI tool ready (`create`, `info`, `validate`, `extract`)
+- ✅ Automated test suite (`node:test`)
+- ✅ Complete documentation
 
 ### 🇧🇷 Made in Brazil
 Harpia AI Research is putting Brazil on the map of AI innovation.
@@ -306,6 +331,7 @@ class VREFWriter {
   
   write(outputPath: string): void;
   getImageCount(): number;
+  clear(): void;
 }
 ```
 
@@ -316,6 +342,7 @@ class VREFReader {
   static read(filePath: string, options?: VREFReadOptions): VREFReadResult;
   static readManifest(filePath: string): VREFManifest;
   static validate(filePath: string): { valid: boolean; errors: string[] };
+  static extract(filePath: string, targetDir: string): void;
 }
 ```
 
@@ -338,7 +365,8 @@ Full API documentation: [TypeScript definitions](src/types.ts)
 
 ### Phase 1 ✅ (Done)
 - Core library implementation
-- CLI tool
+- CLI tool (`create`, `info`, `validate`, `extract`)
+- Automated test coverage
 - npm package published
 - Full documentation
 
@@ -379,7 +407,7 @@ VREF is just getting started. We need:
 
 This project is licensed under the **BSD 3-Clause License** - see the [LICENSE](LICENSE) file for details.
 
-Copyright (c) 2024, Harpia AI Research
+Copyright (c) 2026, Harpia AI Research
 
 ---
 

package/dist/VREFReader.d.ts

@@ -19,4 +19,8 @@ export declare class VREFReader {
         valid: boolean;
         errors: string[];
     };
+    /**
+     * Extract all files from a .vref file to a target directory
+     */
+    static extract(filePath: string, targetDir: string): void;
 }

package/dist/VREFReader.js

@@ -51,6 +51,12 @@ class VREFReader {
         if (!fs.existsSync(filePath)) {
             throw new Error(`File not found: ${filePath}`);
         }
+        if (options.validate) {
+            const validation = VREFReader.validate(filePath);
+            if (!validation.valid) {
+                throw new Error(`Invalid .vref file: ${validation.errors.join(', ')}`);
+            }
+        }
         const zip = new adm_zip_1.default(filePath);
         const zipEntries = zip.getEntries();
         // Find and parse manifest
@@ -181,5 +187,18 @@ class VREFReader {
             return { valid: false, errors };
         }
     }
+    /**
+     * Extract all files from a .vref file to a target directory
+     */
+    static extract(filePath, targetDir) {
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        if (!fs.existsSync(targetDir)) {
+            fs.mkdirSync(targetDir, { recursive: true });
+        }
+        const zip = new adm_zip_1.default(filePath);
+        zip.extractAllTo(targetDir, true);
+    }
 }
 exports.VREFReader = VREFReader;

package/dist/VREFWriter.d.ts

@@ -32,7 +32,7 @@ export declare class VREFWriter {
      */
     private isValidImageBuffer;
     /**
-     * Get image dimensions (basic implementation for PNG and JPEG)
+     * Get image dimensions (supports PNG, JPEG, GIF, WebP)
      */
     private getImageDimensions;
     /**

package/dist/VREFWriter.js

@@ -125,13 +125,14 @@ class VREFWriter {
         }
         // Create manifest
         const manifest = {
-            version: '1.0.0',
+            version: '1.0.2',
             format: 'VREF',
-            fileName: path.basename(outputPath),
+            fileName: this.options.fileName || path.basename(outputPath),
             imageCount: this.images.size,
             images: imageMetadataList,
             createdAt: new Date().toISOString(),
             metadata: {
+                name: this.options.name,
                 description: this.options.description,
                 tags: this.options.tags,
                 author: this.options.author,
@@ -154,28 +155,56 @@ class VREFWriter {
      * Validate image buffer by checking magic bytes
      */
     isValidImageBuffer(buffer, format) {
-        if (buffer.length < 8)
+        if (!buffer || buffer.length < 8)
             return false;
         switch (format.toLowerCase()) {
             case 'png':
-                return buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47;
+                return (buffer.length >= 8 &&
+                    buffer[0] === 0x89 &&
+                    buffer[1] === 0x50 &&
+                    buffer[2] === 0x4e &&
+                    buffer[3] === 0x47);
             case 'jpg':
             case 'jpeg':
-                return buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff;
+                return (buffer.length >= 3 &&
+                    buffer[0] === 0xff &&
+                    buffer[1] === 0xd8 &&
+                    buffer[2] === 0xff);
             case 'gif':
-                return buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46;
+                return (buffer.length >= 6 &&
+                    buffer[0] === 0x47 &&
+                    buffer[1] === 0x49 &&
+                    buffer[2] === 0x46 &&
+                    buffer[3] === 0x38 &&
+                    (buffer[4] === 0x37 || buffer[4] === 0x39) &&
+                    buffer[5] === 0x61);
             case 'webp':
-                return buffer[8] === 0x57 && buffer[9] === 0x45 && buffer[10] === 0x42 && buffer[11] === 0x50;
+                return (buffer.length >= 12 &&
+                    buffer[0] === 0x52 &&
+                    buffer[1] === 0x49 &&
+                    buffer[2] === 0x46 &&
+                    buffer[3] === 0x46 &&
+                    buffer[8] === 0x57 &&
+                    buffer[9] === 0x45 &&
+                    buffer[10] === 0x42 &&
+                    buffer[11] === 0x50);
             case 'avif':
-                // AVIF detection is more complex, but we can check for 'ftyp' box
-                const ftypCheck = buffer.toString('ascii', 4, 8);
-                return ftypCheck === 'ftyp';
+                if (buffer.length < 16)
+                    return false;
+                const ftypBox = buffer.toString('ascii', 4, 8);
+                if (ftypBox !== 'ftyp')
+                    return false;
+                const majorBrand = buffer.toString('ascii', 8, 12);
+                if (majorBrand === 'avif' || majorBrand === 'avis')
+                    return true;
+                const headerSlice = buffer.subarray(12, Math.min(buffer.length, 64)).toString('ascii');
+                return headerSlice.includes('avif') || headerSlice.includes('avis');
             default:
                 return false;
         }
     }
     /**
-     * Get image dimensions (basic implementation for PNG and JPEG)
+     * Get image dimensions (supports PNG, JPEG, GIF, WebP)
      */
     getImageDimensions(buffer, format) {
         try {
@@ -185,8 +214,6 @@ class VREFWriter {
                 return { width, height };
             }
             if ((format === 'jpg' || format === 'jpeg') && buffer.length >= 4) {
-                // Basic JPEG dimension extraction (simplified)
-                // This is a simplified version; production code might use a library
                 let offset = 2;
                 while (offset < buffer.length) {
                     if (buffer[offset] !== 0xff)
@@ -202,6 +229,33 @@ class VREFWriter {
                     offset += segmentLength;
                 }
             }
+            if (format === 'gif' && buffer.length >= 10) {
+                const width = buffer.readUInt16LE(6);
+                const height = buffer.readUInt16LE(8);
+                return { width, height };
+            }
+            if (format === 'webp' && buffer.length >= 30) {
+                const chunkType = buffer.toString('ascii', 12, 16);
+                if (chunkType === 'VP8 ' && buffer.length >= 30) {
+                    const width = buffer.readUInt16LE(26) & 0x3fff;
+                    const height = buffer.readUInt16LE(28) & 0x3fff;
+                    return { width, height };
+                }
+                else if (chunkType === 'VP8L' && buffer.length >= 25) {
+                    const b1 = buffer[21];
+                    const b2 = buffer[22];
+                    const b3 = buffer[23];
+                    const b4 = buffer[24];
+                    const width = 1 + (((b2 & 0x3f) << 8) | b1);
+                    const height = 1 + (((b4 & 0x0f) << 10) | (b3 << 2) | ((b2 & 0xc0) >> 6));
+                    return { width, height };
+                }
+                else if (chunkType === 'VP8X' && buffer.length >= 30) {
+                    const width = 1 + buffer.readUIntLE(24, 3);
+                    const height = 1 + buffer.readUIntLE(27, 3);
+                    return { width, height };
+                }
+            }
         }
         catch (error) {
             // If dimension extraction fails, just return undefined

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * VREF CLI - Command line interface for creating .vref files
+ * VREF CLI - Command line interface for .vref files
  * Harpia AI Research
  */
 export {};

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * VREF CLI - Command line interface for creating .vref files
+ * VREF CLI - Command line interface for .vref files
  * Harpia AI Research
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -41,47 +41,144 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const VREFWriter_1 = require("./VREFWriter");
+const VREFReader_1 = require("./VREFReader");
+const CLI_VERSION = '1.0.2';
 function showHelp() {
     console.log(`
 ┌─────────────────────────────────────────────────┐
-│  VREF CLI v1.0.0                                │
+│  VREF CLI v${CLI_VERSION}                                │
 │  by Harpia AI Research                          │
 │  https://harpiaresearch.cc                      │
 └─────────────────────────────────────────────────┘
 
-Create .vref files from images
+Standardized container for curated visual references in AI image generation
 
 USAGE:
-  npx create-vref <input> [options]
-  
-ARGUMENTS:
-  <input>              Path to image file or directory
+  npx @harpiaresearch/vref <input> [options]
+  vref <command> [arguments]
 
-OPTIONS:
-  -o, --output <path>  Output .vref file path (default: output.vref)
-  -n, --name <name>    Name for the reference pack
-  -d, --desc <text>    Description of the reference pack
-  -t, --tags <tags>    Comma-separated tags
-  -a, --author <name>  Author name
-  -l, --license <lic>  License (e.g., CC-BY-4.0, MIT)
-  -r, --recursive      Include subdirectories
-  -h, --help           Show this help
+COMMANDS:
+  <input> [options]          Create a .vref file from an image or directory
+  info, inspect <file.vref>  Inspect metadata and images in a .vref file
+  validate <file.vref>       Validate integrity and manifest of a .vref file
+  extract <file.vref> [dir]  Extract all images from a .vref file
+
+CREATION OPTIONS:
+  -o, --output <path>   Output .vref file path (default: output.vref)
+  -n, --name <name>     Name/title for the reference pack
+  -d, --desc <text>     Description of the reference pack
+  -t, --tags <tags>     Comma-separated tags
+  -a, --author <name>   Author name
+  -l, --license <lic>   License (e.g., CC-BY-4.0, MIT)
+  -r, --recursive       Include subdirectories
+  -v, --version         Show CLI version
+  -h, --help            Show this help
 
 EXAMPLES:
-  # Create from single image
-  npx create-vref image.png -o references.vref
-  
   # Create from directory
-  npx create-vref ./images -o pack.vref -n "My Pack"
-  
-  # With metadata
-  npx create-vref ./sprites -o rpg-sprites.vref \\
+  npx @harpiaresearch/vref ./images -o pack.vref -n "My Pack"
+
+  # Create with complete metadata
+  npx @harpiaresearch/vref ./sprites -o rpg-sprites.vref \\
     -n "RPG Sprites" \\
     -d "Character sprites for RPG games" \\
     -t "rpg,sprites,pixelart" \\
     -a "Your Name" \\
     -l "CC-BY-4.0"
-  `);
+
+  # Inspect an existing .vref file
+  vref info references.vref
+
+  # Validate file integrity
+  vref validate references.vref
+
+  # Extract images
+  vref extract references.vref ./extracted-images
+`);
+}
+function handleValidate(filePath) {
+    if (!filePath) {
+        console.error('❌ Error: Please specify a .vref file to validate');
+        process.exit(1);
+    }
+    console.log(`🔍 Validating ${filePath}...`);
+    const result = VREFReader_1.VREFReader.validate(filePath);
+    if (result.valid) {
+        const manifest = VREFReader_1.VREFReader.readManifest(filePath);
+        console.log(`✅ Valid .vref file!`);
+        console.log(`   Format: ${manifest.format} (v${manifest.version})`);
+        console.log(`   Images: ${manifest.imageCount}`);
+        if (manifest.metadata?.name)
+            console.log(`   Name: ${manifest.metadata.name}`);
+    }
+    else {
+        console.error(`❌ Validation failed with ${result.errors.length} error(s):`);
+        result.errors.forEach(err => console.error(`   - ${err}`));
+        process.exit(1);
+    }
+}
+function handleInfo(filePath) {
+    if (!filePath) {
+        console.error('❌ Error: Please specify a .vref file to inspect');
+        process.exit(1);
+    }
+    try {
+        const manifest = VREFReader_1.VREFReader.readManifest(filePath);
+        const stats = fs.statSync(filePath);
+        const sizeMB = (stats.size / (1024 * 1024)).toFixed(2);
+        console.log(`\n📦 File: ${path.basename(filePath)} (${sizeMB} MB)`);
+        console.log(`   Format: ${manifest.format} v${manifest.version}`);
+        console.log(`   Created at: ${manifest.createdAt}`);
+        console.log(`   Total images: ${manifest.imageCount}`);
+        if (manifest.metadata) {
+            console.log('\n📋 Metadata:');
+            if (manifest.metadata.name)
+                console.log(`   Name: ${manifest.metadata.name}`);
+            if (manifest.metadata.description)
+                console.log(`   Description: ${manifest.metadata.description}`);
+            if (manifest.metadata.tags && manifest.metadata.tags.length > 0) {
+                console.log(`   Tags: ${manifest.metadata.tags.join(', ')}`);
+            }
+            if (manifest.metadata.author)
+                console.log(`   Author: ${manifest.metadata.author}`);
+            if (manifest.metadata.license)
+                console.log(`   License: ${manifest.metadata.license}`);
+        }
+        if (manifest.images.length > 0) {
+            console.log('\n🖼️ Sample of contained images:');
+            const previewCount = Math.min(manifest.images.length, 5);
+            for (let i = 0; i < previewCount; i++) {
+                const img = manifest.images[i];
+                const dim = img.width && img.height ? ` (${img.width}x${img.height})` : '';
+                const sizeKB = (img.size / 1024).toFixed(1);
+                console.log(`   - ${img.path} [${img.format.toUpperCase()}]${dim} - ${sizeKB} KB`);
+            }
+            if (manifest.images.length > previewCount) {
+                console.log(`   ... and ${manifest.images.length - previewCount} more`);
+            }
+        }
+        console.log();
+    }
+    catch (error) {
+        console.error(`❌ Error inspecting file: ${error.message}`);
+        process.exit(1);
+    }
+}
+function handleExtract(filePath, outputDir) {
+    if (!filePath) {
+        console.error('❌ Error: Please specify a .vref file to extract');
+        process.exit(1);
+    }
+    const targetDir = outputDir || path.join(process.cwd(), path.basename(filePath, '.vref') + '_extracted');
+    try {
+        console.log(`📦 Extracting ${filePath} to ${targetDir}...`);
+        VREFReader_1.VREFReader.extract(filePath, targetDir);
+        console.log(`✅ Extracted successfully to ${targetDir}`);
+    }
+    catch (error) {
+        console.error(`❌ Extraction error: ${error.message}`);
+        process.exit(1);
+    }
 }
 function parseArgs(args) {
     const options = {
@@ -102,6 +199,11 @@ function parseArgs(args) {
                 showHelp();
                 process.exit(0);
                 break;
+            case '-v':
+            case '--version':
+                console.log(`v${CLI_VERSION}`);
+                process.exit(0);
+                break;
             case '-o':
             case '--output':
                 options.output = args[++i];
@@ -117,7 +219,7 @@ function parseArgs(args) {
                 break;
             case '-t':
             case '--tags':
-                options.tags = args[++i].split(',').map((t) => t.trim());
+                options.tags = args[++i]?.split(',').map((t) => t.trim());
                 break;
             case '-a':
             case '--author':
@@ -132,7 +234,7 @@ function parseArgs(args) {
                 options.recursive = true;
                 break;
             default:
-                if (!arg.startsWith('-')) {
+                if (!arg.startsWith('-') && !options.input) {
                     options.input = arg;
                 }
                 break;
@@ -146,10 +248,31 @@ function main() {
         showHelp();
         process.exit(0);
     }
+    const firstArg = args[0];
+    if (firstArg === 'validate') {
+        handleValidate(args[1]);
+        return;
+    }
+    if (firstArg === 'info' || firstArg === 'inspect') {
+        handleInfo(args[1]);
+        return;
+    }
+    if (firstArg === 'extract') {
+        handleExtract(args[1], args[2]);
+        return;
+    }
+    if (firstArg === '-h' || firstArg === '--help') {
+        showHelp();
+        process.exit(0);
+    }
+    if (firstArg === '-v' || firstArg === '--version') {
+        console.log(`v${CLI_VERSION}`);
+        process.exit(0);
+    }
     const options = parseArgs(args);
     if (!options.input) {
         console.error('❌ Error: No input specified');
-        console.log('Run "npx create-vref --help" for usage information');
+        console.log('Run "npx @harpiaresearch/vref --help" for usage information');
         process.exit(1);
     }
     if (!fs.existsSync(options.input)) {
@@ -157,13 +280,13 @@ function main() {
         process.exit(1);
     }
     console.log('┌─────────────────────────────────────────────────┐');
-    console.log('│  VREF CLI v1.0.0                                │');
+    console.log(`│  VREF CLI v${CLI_VERSION}                                │`);
     console.log('│  by Harpia AI Research                          │');
     console.log('└─────────────────────────────────────────────────┘\n');
     try {
-        const fileName = options.name || path.basename(options.output, '.vref');
         const writer = new VREFWriter_1.VREFWriter({
-            fileName: options.output,
+            fileName: path.basename(options.output),
+            name: options.name,
             description: options.description,
             tags: options.tags,
             author: options.author,

package/dist/types.d.ts

@@ -23,6 +23,8 @@ export interface VREFManifest {
     createdAt: string;
     /** Optional metadata */
     metadata?: {
+        /** Human-readable title/name of the reference pack */
+        name?: string;
         /** Description of the reference pack */
         description?: string;
         /** Tags for categorization */
@@ -54,8 +56,10 @@ export interface ImageMetadata {
  * Options for creating a VREF file
  */
 export interface VREFCreateOptions {
-    /** Name for the output .vref file */
-    fileName: string;
+    /** Optional name/title for the reference pack */
+    name?: string;
+    /** Name for the output .vref file (optional, defaults to output path file name) */
+    fileName?: string;
     /** Optional description */
     description?: string;
     /** Optional tags */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harpiaresearch/vref",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Visual Reference Format - Standardized container for curated visual references in AI image generation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,8 +10,8 @@
     "LICENSE"
   ],
   "bin": {
-    "create-vref": "./dist/cli.js",
-    "vref": "./dist/cli.js"
+    "create-vref": "dist/cli.js",
+    "vref": "dist/cli.js"
   },
   "scripts": {
     "build": "tsc",
@@ -32,7 +32,7 @@
   "license": "BSD-3-Clause",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Harpia-AI-Research/vref"
+    "url": "git+https://github.com/Harpia-AI-Research/vref.git"
   },
   "dependencies": {
     "adm-zip": "^0.5.10"