@mytechtoday/url-reference-mapper 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-01-28
+
+### Added
+- Initial release of @mytechtoday/url-reference-mapper
+- Core `UrlReferenceMapper` class with bidirectional lookup
+- Support for JSON and YAML configuration files
+- CLI commands: `init`, `add`, `get-url`, `get-path`, `validate`, `export`
+- TypeScript declarations for full type safety
+- Seed data with 4 copper mining blog post mappings
+- Export functionality to JSON, YAML, and CSV formats
+- Comprehensive validation with errors and warnings
+- MIT License
+
+### Features
+- Bidirectional mapping between local paths and published URLs
+- Auto-save functionality for programmatic updates
+- Duplicate detection for URLs and paths
+- Path normalization for cross-platform compatibility
+- ISO 8601 timestamps for tracking updates
+- Integration-ready for Augment AI, OpenSpec, and beads workflows
+
+[1.0.0]: https://github.com/mytech-today-now/url-reference-mapper/releases/tag/v1.0.0
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 MyTech.Today
+
+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

@@ -0,0 +1,397 @@
+# @mytechtoday/url-reference
+
+**Bidirectional mapping between local filesystem paths and published internet URLs for Augment AI workflows.**
+
+[![npm version](https://img.shields.io/npm/v/@mytechtoday/url-reference.svg)](https://www.npmjs.com/package/@mytechtoday/url-reference)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🎯 Purpose
+
+Eliminate broken local-file links in AI-generated content when publishing to the web. This package provides a clean, reusable solution for mapping local development paths to published URLs, specifically designed for:
+
+- **Augment AI** workflows
+- **OpenSpec** spec-driven development
+- **Beads** issue tracking integration
+- WordPress publishing
+- Static site generation
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install @mytechtoday/url-reference
+```
+
+### Initialize Configuration
+
+```bash
+npx url-ref-mapper init
+```
+
+This creates a `url-references.json` file with seed data for 4 copper mining blog posts.
+
+### Programmatic Usage
+
+```typescript
+import { UrlReferenceMapper } from '@mytechtoday/url-reference';
+
+const mapper = new UrlReferenceMapper({
+  configPath: './url-references.json'
+});
+
+// Get published URL from local path
+// Windows
+const url = mapper.getUrlFromLocalPath("C:\\projects\\blog\\post.html");
+// macOS/Linux
+const url = mapper.getUrlFromLocalPath("/home/user/projects/blog/post.html");
+// → "https://mytech.today/published-url/"
+
+// Reverse lookup
+const path = mapper.getLocalPathFromUrl("https://mytech.today/published-url/");
+// → "C:\\projects\\blog\\post.html" (Windows)
+// → "/home/user/projects/blog/post.html" (macOS/Linux)
+
+// Add new mapping
+mapper.addMapping({
+  title: "New Blog Post",
+  url: "https://mytech.today/new-post/",
+  localPath: "C:\\projects\\blog\\new-post.html"  // Windows
+  // localPath: "/home/user/projects/blog/new-post.html"  // macOS/Linux
+});
+
+mapper.save();
+```
+
+## 📖 API Documentation
+
+### `UrlReferenceMapper`
+
+#### Constructor
+
+```typescript
+new UrlReferenceMapper(config?: UrlReferenceMapperConfig)
+```
+
+**Config Options:**
+- `configPath?: string` - Path to JSON/YAML configuration file
+- `mappings?: UrlMapping[]` - Inline mappings for testing
+- `autoSave?: boolean` - Auto-save changes to config file (default: false)
+
+#### Methods
+
+##### `getUrlFromLocalPath(localPath: string): string | null`
+Get published URL from local filesystem path.
+
+##### `getLocalPathFromUrl(url: string): string | null`
+Get local filesystem path from published URL.
+
+##### `addMapping(mapping: UrlMapping): void`
+Add a new URL-to-path mapping. Throws error if URL or path already exists.
+
+##### `updateMapping(url: string, updates: Partial<UrlMapping>): void`
+Update an existing mapping by URL.
+
+##### `removeMapping(url: string): boolean`
+Remove a mapping by URL. Returns true if removed.
+
+##### `getAllMappings(): UrlMapping[]`
+Get all mappings as an array.
+
+##### `save(filePath?: string): void`
+Save mappings to file (JSON or YAML based on extension).
+
+##### `validate(): ValidationResult`
+Validate all mappings. Returns errors and warnings.
+
+##### `export(format: ExportFormat): string`
+Export mappings to JSON, YAML, or CSV format.
+
+### Types
+
+```typescript
+interface UrlMapping {
+  title: string;
+  url: string;
+  localPath: string;
+  lastUpdated?: string;
+}
+
+interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+type ExportFormat = 'json' | 'yaml' | 'csv';
+```
+
+## 🔧 CLI Commands
+
+### `init`
+Create a default configuration file with seed data.
+
+```bash
+npx url-ref-mapper init
+npx url-ref-mapper init --format yaml --path custom-path.yaml
+```
+
+### `add`
+Add a new mapping.
+
+**Windows:**
+```bash
+npx url-ref-mapper add ^
+  --title "My Blog Post" ^
+  --url "https://example.com/post/" ^
+  --path "C:\projects\blog\post.html"
+```
+
+**macOS/Linux:**
+```bash
+npx url-ref-mapper add \
+  --title "My Blog Post" \
+  --url "https://example.com/post/" \
+  --path "/home/user/projects/blog/post.html"
+```
+
+### `get-url`
+Get published URL from local path.
+
+**Windows:**
+```bash
+npx url-ref-mapper get-url "C:\projects\blog\post.html"
+```
+
+**macOS/Linux:**
+```bash
+npx url-ref-mapper get-url "/home/user/projects/blog/post.html"
+```
+
+### `get-path`
+Get local path from published URL.
+
+```bash
+npx url-ref-mapper get-path "https://example.com/post/"
+```
+
+### `validate`
+Validate all mappings.
+
+```bash
+npx url-ref-mapper validate
+```
+
+### `export`
+Export mappings to different formats.
+
+```bash
+npx url-ref-mapper export --format csv --output mappings.csv
+npx url-ref-mapper export --format yaml
+```
+
+## 🤖 Augment AI Integration
+
+This package is designed to work seamlessly with Augment AI workflows:
+
+### In OpenSpec Documents
+
+Reference the package in your spec files:
+
+```markdown
+Use @mytechtoday/url-reference to resolve local paths to published URLs.
+```
+
+### In Beads Tasks
+
+```bash
+# Create a task that uses the mapper
+bd create "Update URL mappings for new blog posts"
+
+# In your code
+import { UrlReferenceMapper } from '@mytechtoday/url-reference';
+const mapper = new UrlReferenceMapper({ configPath: './url-references.json' });
+```
+
+### With Augment Extensions
+
+This package works alongside `@mytechtoday/augment-extensions`:
+
+```bash
+# Install both
+npm install -g @mytechtoday/augment-extensions
+npm install @mytechtoday/url-reference
+
+# Use together in your project
+augx link coding-standards/typescript
+```
+
+## 📁 Configuration File Format
+
+### JSON Format (default)
+
+**Windows:**
+```json
+[
+  {
+    "title": "Copper ETFs and Investment Vehicles: 2026",
+    "url": "https://mytech.today/copper-etfs-and-investment-vehicles-2026/",
+    "localPath": "C:\\projects\\blogs\\copper-mining-part-4-etf-investment-vehicles.html",
+    "lastUpdated": "2026-01-27T17:04:00-06:00"
+  }
+]
+```
+
+**macOS/Linux:**
+```json
+[
+  {
+    "title": "Copper ETFs and Investment Vehicles: 2026",
+    "url": "https://mytech.today/copper-etfs-and-investment-vehicles-2026/",
+    "localPath": "/home/user/projects/blogs/copper-mining-part-4-etf-investment-vehicles.html",
+    "lastUpdated": "2026-01-27T17:04:00-06:00"
+  }
+]
+```
+
+### YAML Format
+
+**Windows:**
+```yaml
+- title: Copper ETFs and Investment Vehicles: 2026
+  url: https://mytech.today/copper-etfs-and-investment-vehicles-2026/
+  localPath: C:\projects\blogs\copper-mining-part-4-etf-investment-vehicles.html
+  lastUpdated: '2026-01-27T17:04:00-06:00'
+```
+
+**macOS/Linux:**
+```yaml
+- title: Copper ETFs and Investment Vehicles: 2026
+  url: https://mytech.today/copper-etfs-and-investment-vehicles-2026/
+  localPath: /home/user/projects/blogs/copper-mining-part-4-etf-investment-vehicles.html
+  lastUpdated: '2026-01-27T17:04:00-06:00'
+```
+
+## 🌍 Cross-Platform Support
+
+This package works seamlessly across **Windows**, **macOS**, and **Linux** platforms.
+
+### Path Format Guidelines
+
+**Windows:**
+- Use backslashes: `C:\projects\blog\post.html`
+- Or forward slashes: `C:/projects/blog/post.html`
+- Both formats are supported and normalized internally
+
+**macOS/Linux:**
+- Use forward slashes: `/home/user/projects/blog/post.html`
+- Absolute paths recommended for consistency
+
+### Platform-Specific Examples
+
+**Windows (PowerShell):**
+```powershell
+# Initialize config
+npx url-ref-mapper init
+
+# Add mapping
+npx url-ref-mapper add `
+  --title "My Post" `
+  --url "https://example.com/post/" `
+  --path "C:\projects\blog\post.html"
+
+# Get URL
+npx url-ref-mapper get-url "C:\projects\blog\post.html"
+```
+
+**macOS/Linux (Bash/Zsh):**
+```bash
+# Initialize config
+npx url-ref-mapper init
+
+# Add mapping
+npx url-ref-mapper add \
+  --title "My Post" \
+  --url "https://example.com/post/" \
+  --path "/home/user/projects/blog/post.html"
+
+# Get URL
+npx url-ref-mapper get-url "/home/user/projects/blog/post.html"
+```
+
+## 🧪 Testing
+
+```bash
+npm test
+npm run test:coverage
+```
+
+## 🛠 Development
+
+```bash
+# Clone the repository
+git clone https://github.com/mytech-today-now/url-reference.git
+cd url-reference
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run in development mode
+npm run dev
+
+# Lint
+npm run lint
+npm run lint:fix
+
+# Format
+npm run format
+```
+
+## 📦 Publishing
+
+```bash
+# Build and test
+npm run build
+npm test
+
+# Publish to npm
+npm publish
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🔗 Related Projects
+
+- [Augment Code AI](https://www.augmentcode.com/) - AI coding assistant
+- [OpenSpec](https://github.com/Fission-AI/OpenSpec) - Spec-driven development
+- [Beads](https://github.com/steveyegge/beads) - Distributed issue tracker
+- [Augment Extensions](https://github.com/mytech-today-now/augment) - Extension modules for Augment AI
+
+## 📞 Support
+
+- **Issues**: [GitHub Issues](https://github.com/mytech-today-now/url-reference/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/mytech-today-now/url-reference/discussions)
+
+## 🌟 Acknowledgments
+
+Built for the Augment AI community to solve the common problem of broken local file references in AI-generated content.
+
+---
+
+**Status**: Production Ready | **Version**: 1.0.0 | **Maintainer**: MyTech.Today
+

package/dist/UrlReferenceMapper.d.ts

@@ -0,0 +1,23 @@
+import { UrlMapping, UrlReferenceMapperConfig, ValidationResult, ExportFormat } from './types';
+export declare class UrlReferenceMapper {
+    private mappings;
+    private urlToMapping;
+    private pathToMapping;
+    private configPath?;
+    private autoSave;
+    private validateOnLoad;
+    private allowDuplicates;
+    constructor(config?: UrlReferenceMapperConfig);
+    private rebuildIndexes;
+    private loadFromFile;
+    getUrlFromLocalPath(localPath: string): string | null;
+    getLocalPathFromUrl(url: string): string | null;
+    addMapping(mapping: UrlMapping): void;
+    updateMapping(url: string, updates: Partial<UrlMapping>): void;
+    removeMapping(url: string): boolean;
+    getAllMappings(): UrlMapping[];
+    save(filePath?: string): void;
+    validate(): ValidationResult;
+    export(format: ExportFormat): string;
+}
+//# sourceMappingURL=UrlReferenceMapper.d.ts.map

package/dist/UrlReferenceMapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UrlReferenceMapper.d.ts","sourceRoot":"","sources":["../src/UrlReferenceMapper.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,wBAAwB,EAAE,gBAAgB,EAAsC,YAAY,EAAE,MAAM,SAAS,CAAC;AAKnI,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,YAAY,CAAsC;IAC1D,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,eAAe,CAAU;gBAErB,MAAM,GAAE,wBAA6B;IA4BjD,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,YAAY;IAsBpB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IASrD,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAQ/C,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;IAiCrC,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAsC9D,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAwBnC,cAAc,IAAI,UAAU,EAAE;IAO9B,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAuB7B,QAAQ,IAAI,gBAAgB;IAuG5B,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;CAoBrC"}

package/dist/UrlReferenceMapper.js

@@ -0,0 +1,268 @@
+"use strict";
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UrlReferenceMapper = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const yaml = __importStar(require("js-yaml"));
+class UrlReferenceMapper {
+    constructor(config = {}) {
+        this.mappings = [];
+        this.urlToMapping = new Map();
+        this.pathToMapping = new Map();
+        this.configPath = config.configPath;
+        this.autoSave = config.autoSave ?? false;
+        this.validateOnLoad = config.validateOnLoad ?? true;
+        this.allowDuplicates = config.allowDuplicates ?? false;
+        if (config.mappings) {
+            this.mappings = config.mappings;
+            this.rebuildIndexes();
+        }
+        else if (config.configPath) {
+            this.loadFromFile(config.configPath);
+        }
+        if (this.validateOnLoad && this.mappings.length > 0) {
+            const validationResult = this.validate();
+            if (!validationResult.valid) {
+                throw new Error(`Validation failed on load:\n` +
+                    validationResult.errors.map(e => `  - [${e.type}] ${e.message}`).join('\n'));
+            }
+        }
+    }
+    rebuildIndexes() {
+        this.urlToMapping.clear();
+        this.pathToMapping.clear();
+        for (const mapping of this.mappings) {
+            this.urlToMapping.set(mapping.url, mapping);
+            const normalizedPath = path.normalize(mapping.localPath);
+            this.pathToMapping.set(normalizedPath, mapping);
+        }
+    }
+    loadFromFile(filePath) {
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`Configuration file not found: ${filePath}`);
+        }
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const ext = path.extname(filePath).toLowerCase();
+        if (ext === '.json') {
+            this.mappings = JSON.parse(content);
+        }
+        else if (ext === '.yaml' || ext === '.yml') {
+            this.mappings = yaml.load(content);
+        }
+        else {
+            throw new Error(`Unsupported file format: ${ext}. Use .json, .yaml, or .yml`);
+        }
+        this.rebuildIndexes();
+    }
+    getUrlFromLocalPath(localPath) {
+        const normalized = path.normalize(localPath);
+        const mapping = this.pathToMapping.get(normalized);
+        return mapping ? mapping.url : null;
+    }
+    getLocalPathFromUrl(url) {
+        const mapping = this.urlToMapping.get(url);
+        return mapping ? mapping.localPath : null;
+    }
+    addMapping(mapping) {
+        if (!this.allowDuplicates) {
+            const normalizedPath = path.normalize(mapping.localPath);
+            if (this.urlToMapping.has(mapping.url)) {
+                throw new Error(`URL already exists: ${mapping.url}`);
+            }
+            if (this.pathToMapping.has(normalizedPath)) {
+                throw new Error(`Local path already exists: ${mapping.localPath}`);
+            }
+        }
+        if (!mapping.lastUpdated) {
+            mapping.lastUpdated = new Date().toISOString();
+        }
+        this.mappings.push(mapping);
+        this.urlToMapping.set(mapping.url, mapping);
+        const normalizedPath = path.normalize(mapping.localPath);
+        this.pathToMapping.set(normalizedPath, mapping);
+        if (this.autoSave && this.configPath) {
+            this.save();
+        }
+    }
+    updateMapping(url, updates) {
+        const mapping = this.urlToMapping.get(url);
+        if (!mapping) {
+            throw new Error(`Mapping not found for URL: ${url}`);
+        }
+        if (updates.localPath && updates.localPath !== mapping.localPath) {
+            const oldNormalizedPath = path.normalize(mapping.localPath);
+            this.pathToMapping.delete(oldNormalizedPath);
+        }
+        const updatedMapping = {
+            ...mapping,
+            ...updates,
+            lastUpdated: new Date().toISOString()
+        };
+        const index = this.mappings.findIndex(m => m.url === url);
+        if (index !== -1) {
+            this.mappings[index] = updatedMapping;
+        }
+        this.urlToMapping.set(url, updatedMapping);
+        const newNormalizedPath = path.normalize(updatedMapping.localPath);
+        this.pathToMapping.set(newNormalizedPath, updatedMapping);
+        if (this.autoSave && this.configPath) {
+            this.save();
+        }
+    }
+    removeMapping(url) {
+        const mapping = this.urlToMapping.get(url);
+        if (!mapping) {
+            return false;
+        }
+        this.mappings = this.mappings.filter(m => m.url !== url);
+        this.urlToMapping.delete(url);
+        const normalizedPath = path.normalize(mapping.localPath);
+        this.pathToMapping.delete(normalizedPath);
+        if (this.autoSave && this.configPath) {
+            this.save();
+        }
+        return true;
+    }
+    getAllMappings() {
+        return [...this.mappings];
+    }
+    save(filePath) {
+        const targetPath = filePath || this.configPath;
+        if (!targetPath) {
+            throw new Error('No file path specified for saving');
+        }
+        const ext = path.extname(targetPath).toLowerCase();
+        let content;
+        if (ext === '.json') {
+            content = JSON.stringify(this.mappings, null, 2);
+        }
+        else if (ext === '.yaml' || ext === '.yml') {
+            content = yaml.dump(this.mappings);
+        }
+        else {
+            throw new Error(`Unsupported file format: ${ext}. Use .json, .yaml, or .yml`);
+        }
+        fs.writeFileSync(targetPath, content, 'utf-8');
+    }
+    validate() {
+        const errors = [];
+        const warnings = [];
+        const urls = new Set();
+        const paths = new Set();
+        for (const mapping of this.mappings) {
+            if (!mapping.title || !mapping.url || !mapping.localPath) {
+                errors.push({
+                    type: 'invalid_format',
+                    message: `Missing required fields in mapping: ${JSON.stringify(mapping)}`,
+                    mapping
+                });
+                continue;
+            }
+            if (urls.has(mapping.url)) {
+                errors.push({
+                    type: 'duplicate_url',
+                    message: `Duplicate URL found: ${mapping.url}`,
+                    mapping
+                });
+            }
+            urls.add(mapping.url);
+            const normalizedPath = path.normalize(mapping.localPath);
+            if (paths.has(normalizedPath)) {
+                errors.push({
+                    type: 'duplicate_path',
+                    message: `Duplicate local path found: ${mapping.localPath}`,
+                    mapping
+                });
+            }
+            paths.add(normalizedPath);
+            try {
+                new URL(mapping.url);
+            }
+            catch {
+                errors.push({
+                    type: 'invalid_url',
+                    message: `Invalid URL format: ${mapping.url}`,
+                    mapping
+                });
+            }
+            if (!fs.existsSync(mapping.localPath)) {
+                warnings.push({
+                    type: 'missing_file',
+                    message: `Local file not found: ${mapping.localPath}`,
+                    mapping
+                });
+            }
+            if (!path.isAbsolute(mapping.localPath)) {
+                warnings.push({
+                    type: 'relative_path',
+                    message: `Relative path detected (absolute paths recommended): ${mapping.localPath}`,
+                    mapping
+                });
+            }
+            if (!mapping.metadata || Object.keys(mapping.metadata).length === 0) {
+                warnings.push({
+                    type: 'missing_metadata',
+                    message: `Missing metadata for mapping: ${mapping.title}`,
+                    mapping
+                });
+            }
+            if (mapping.lastUpdated) {
+                const lastUpdated = new Date(mapping.lastUpdated);
+                const now = new Date();
+                const daysDiff = (now.getTime() - lastUpdated.getTime()) / (1000 * 60 * 60 * 24);
+                if (daysDiff > 90) {
+                    warnings.push({
+                        type: 'outdated_timestamp',
+                        message: `Mapping not updated in ${Math.floor(daysDiff)} days: ${mapping.title}`,
+                        mapping
+                    });
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    export(format) {
+        switch (format) {
+            case 'json':
+                return JSON.stringify(this.mappings, null, 2);
+            case 'yaml':
+                return yaml.dump(this.mappings);
+            case 'csv': {
+                const headers = 'Title,URL,Local Path,Last Updated\n';
+                const rows = this.mappings.map(m => `"${m.title}","${m.url}","${m.localPath}","${m.lastUpdated || ''}"`).join('\n');
+                return headers + rows;
+            }
+            default:
+                throw new Error(`Unsupported export format: ${format}`);
+        }
+    }
+}
+exports.UrlReferenceMapper = UrlReferenceMapper;
+//# sourceMappingURL=UrlReferenceMapper.js.map

package/dist/UrlReferenceMapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UrlReferenceMapper.js","sourceRoot":"","sources":["../src/UrlReferenceMapper.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,uCAAyB;AACzB,2CAA6B;AAC7B,8CAAgC;AAMhC,MAAa,kBAAkB;IAS7B,YAAY,SAAmC,EAAE;QARzC,aAAQ,GAAiB,EAAE,CAAC;QAC5B,iBAAY,GAA4B,IAAI,GAAG,EAAE,CAAC;QAClD,kBAAa,GAA4B,IAAI,GAAG,EAAE,CAAC;QAOzD,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QACpC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,KAAK,CAAC;QACzC,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC,cAAc,IAAI,IAAI,CAAC;QACpD,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,IAAI,KAAK,CAAC;QAEvD,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;YAChC,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,CAAC;aAAM,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YAC7B,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACvC,CAAC;QAGD,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,MAAM,gBAAgB,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YACzC,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CACb,8BAA8B;oBAC9B,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAC5E,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAKO,cAAc;QACpB,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAE3B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC5C,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YACzD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAKO,YAAY,CAAC,QAAgB;QACnC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,iCAAiC,QAAQ,EAAE,CAAC,CAAC;QAC/D,CAAC;QAED,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;QAEjD,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;YACpB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;aAAM,IAAI,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;YAC7C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAiB,CAAC;QACrD,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,4BAA4B,GAAG,6BAA6B,CAAC,CAAC;QAChF,CAAC;QAED,IAAI,CAAC,cAAc,EAAE,CAAC;IACxB,CAAC;IAKD,mBAAmB,CAAC,SAAiB;QACnC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACnD,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IACtC,CAAC;IAKD,mBAAmB,CAAC,GAAW;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3C,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5C,CAAC;IAKD,UAAU,CAAC,OAAmB;QAE5B,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC1B,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAEzD,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBACvC,MAAM,IAAI,KAAK,CAAC,uBAAuB,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;YACxD,CAAC;YACD,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;gBAC3C,MAAM,IAAI,KAAK,CAAC,8BAA8B,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;YACrE,CAAC;QACH,CAAC;QAGD,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YACzB,OAAO,CAAC,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACjD,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAG5B,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC5C,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;QAEhD,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACrC,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,CAAC;IACH,CAAC;IAKD,aAAa,CAAC,GAAW,EAAE,OAA4B;QACrD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,EAAE,CAAC,CAAC;QACvD,CAAC;QAGD,IAAI,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC;YACjE,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAC5D,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;QAC/C,CAAC;QAGD,MAAM,cAAc,GAAG;YACrB,GAAG,OAAO;YACV,GAAG,OAAO;YACV,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACtC,CAAC;QAGF,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;QAC1D,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;YACjB,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,cAAc,CAAC;QACxC,CAAC;QAGD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QAC3C,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QACnE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,iBAAiB,EAAE,cAAc,CAAC,CAAC;QAE1D,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACrC,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,CAAC;IACH,CAAC;IAKD,aAAa,CAAC,GAAW;QACvB,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,KAAK,CAAC;QACf,CAAC;QAGD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;QAGzD,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzD,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QAE1C,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACrC,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAKD,cAAc;QACZ,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAKD,IAAI,CAAC,QAAiB;QACpB,MAAM,UAAU,GAAG,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC;QAC/C,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC;QACnD,IAAI,OAAe,CAAC;QAEpB,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;YACpB,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QACnD,CAAC;aAAM,IAAI,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;YAC7C,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrC,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,4BAA4B,GAAG,6BAA6B,CAAC,CAAC;QAChF,CAAC;QAED,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;IAKD,QAAQ;QACN,MAAM,MAAM,GAAsB,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAwB,EAAE,CAAC;QAGzC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;QAEhC,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAEpC,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;gBACzD,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,gBAAgB;oBACtB,OAAO,EAAE,uCAAuC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE;oBACzE,OAAO;iBACR,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAGD,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC1B,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,eAAe;oBACrB,OAAO,EAAE,wBAAwB,OAAO,CAAC,GAAG,EAAE;oBAC9C,OAAO;iBACR,CAAC,CAAC;YACL,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAGtB,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YACzD,IAAI,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;gBAC9B,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,gBAAgB;oBACtB,OAAO,EAAE,+BAA+B,OAAO,CAAC,SAAS,EAAE;oBAC3D,OAAO;iBACR,CAAC,CAAC;YACL,CAAC;YACD,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;YAG1B,IAAI,CAAC;gBACH,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,aAAa;oBACnB,OAAO,EAAE,uBAAuB,OAAO,CAAC,GAAG,EAAE;oBAC7C,OAAO;iBACR,CAAC,CAAC;YACL,CAAC;YAGD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;gBACtC,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,cAAc;oBACpB,OAAO,EAAE,yBAAyB,OAAO,CAAC,SAAS,EAAE;oBACrD,OAAO;iBACR,CAAC,CAAC;YACL,CAAC;YAGD,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;gBACxC,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,eAAe;oBACrB,OAAO,EAAE,wDAAwD,OAAO,CAAC,SAAS,EAAE;oBACpF,OAAO;iBACR,CAAC,CAAC;YACL,CAAC;YAGD,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACpE,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,kBAAkB;oBACxB,OAAO,EAAE,iCAAiC,OAAO,CAAC,KAAK,EAAE;oBACzD,OAAO;iBACR,CAAC,CAAC;YACL,CAAC;YAGD,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;gBACxB,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;gBAClD,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;gBACjF,IAAI,QAAQ,GAAG,EAAE,EAAE,CAAC;oBAClB,QAAQ,CAAC,IAAI,CAAC;wBACZ,IAAI,EAAE,oBAAoB;wBAC1B,OAAO,EAAE,0BAA0B,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,OAAO,CAAC,KAAK,EAAE;wBAChF,OAAO;qBACR,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;YAC1B,MAAM;YACN,QAAQ;SACT,CAAC;IACJ,CAAC;IAKD,MAAM,CAAC,MAAoB;QACzB,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,MAAM;gBACT,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YAEhD,KAAK,MAAM;gBACT,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAElC,KAAK,KAAK,CAAC,CAAC,CAAC;gBACX,MAAM,OAAO,GAAG,qCAAqC,CAAC;gBACtD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CACjC,IAAI,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC,WAAW,IAAI,EAAE,GAAG,CACpE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACb,OAAO,OAAO,GAAG,IAAI,CAAC;YACxB,CAAC;YAED;gBACE,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,EAAE,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;CACF;AAlVD,gDAkVC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+"use strict";
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const fs = __importStar(require("fs"));
+const UrlReferenceMapper_1 = require("./UrlReferenceMapper");
+const yaml = __importStar(require("js-yaml"));
+const program = new commander_1.Command();
+program
+    .name('url-ref-mapper')
+    .description('CLI tool for managing URL-to-path mappings')
+    .version('1.0.0');
+program
+    .command('init')
+    .description('Create a default url-references.json configuration file')
+    .option('-f, --format <format>', 'File format (json or yaml)', 'json')
+    .option('-p, --path <path>', 'Output file path', 'url-references.json')
+    .action((options) => {
+    const filePath = options.path;
+    const format = options.format;
+    if (fs.existsSync(filePath)) {
+        console.error(`Error: File already exists: ${filePath}`);
+        process.exit(1);
+    }
+    const seedData = [
+        {
+            title: "Copper ETFs and Investment Vehicles: 2026",
+            url: "https://mytech.today/copper-etfs-and-investment-vehicles-2026/",
+            localPath: "C:\\projects\\blogs\\copper-mining-part-4-etf-investment-vehicles.html",
+            lastUpdated: new Date().toISOString()
+        },
+        {
+            title: "Mid-Tier & Junior Copper Miners: 2026 Analysis",
+            url: "https://mytech.today/mid-tier-junior-copper-miners-2026-analysis/",
+            localPath: "C:\\projects\\blogs\\copper-mining-part-3-mid-tier-junior-companies.html",
+            lastUpdated: new Date().toISOString()
+        },
+        {
+            title: "Copper Demand vs Supply: 2026-2040 Outlook",
+            url: "https://mytech.today/copper-demand-vs-supply-2026-2040-outlook/",
+            localPath: "C:\\projects\\blogs\\copper-mining-part-1-demand-supply-outlook.html",
+            lastUpdated: new Date().toISOString()
+        },
+        {
+            title: "Major Copper Mining Companies Analysis 2026",
+            url: "https://mytech.today/major-copper-mining-companies-analysis-2026/",
+            localPath: "C:\\projects\\blogs\\copper-mining-part-2-major-companies-analysis.html",
+            lastUpdated: new Date().toISOString()
+        }
+    ];
+    const mapper = new UrlReferenceMapper_1.UrlReferenceMapper({ mappings: seedData });
+    const outputPath = format === 'yaml' ? filePath.replace(/\.json$/, '.yaml') : filePath;
+    mapper.save(outputPath);
+    console.log(`✓ Created ${outputPath} with ${seedData.length} seed mappings`);
+});
+program
+    .command('add')
+    .description('Add a new URL-to-path mapping')
+    .requiredOption('-t, --title <title>', 'Title of the mapping')
+    .requiredOption('-u, --url <url>', 'Published URL')
+    .requiredOption('-p, --path <path>', 'Local filesystem path')
+    .option('-c, --config <config>', 'Config file path', 'url-references.json')
+    .action((options) => {
+    const mapper = new UrlReferenceMapper_1.UrlReferenceMapper({
+        configPath: options.config,
+        autoSave: true
+    });
+    const mapping = {
+        title: options.title,
+        url: options.url,
+        localPath: options.path,
+        lastUpdated: new Date().toISOString()
+    };
+    try {
+        mapper.addMapping(mapping);
+        console.log(`✓ Added mapping: ${options.title}`);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command('get-url <localPath>')
+    .description('Get published URL from local path')
+    .option('-c, --config <config>', 'Config file path', 'url-references.json')
+    .action((localPath, options) => {
+    const mapper = new UrlReferenceMapper_1.UrlReferenceMapper({ configPath: options.config });
+    const url = mapper.getUrlFromLocalPath(localPath);
+    if (url) {
+        console.log(url);
+    }
+    else {
+        console.error(`No URL found for path: ${localPath}`);
+        process.exit(1);
+    }
+});
+program
+    .command('get-path <url>')
+    .description('Get local path from published URL')
+    .option('-c, --config <config>', 'Config file path', 'url-references.json')
+    .action((url, options) => {
+    const mapper = new UrlReferenceMapper_1.UrlReferenceMapper({ configPath: options.config });
+    const localPath = mapper.getLocalPathFromUrl(url);
+    if (localPath) {
+        console.log(localPath);
+    }
+    else {
+        console.error(`No local path found for URL: ${url}`);
+        process.exit(1);
+    }
+});
+program
+    .command('list')
+    .description('List all URL-to-path mappings')
+    .option('-c, --config <config>', 'Config file path', 'url-references.json')
+    .option('-f, --format <format>', 'Output format (table, json, yaml)', 'table')
+    .action((options) => {
+    const mapper = new UrlReferenceMapper_1.UrlReferenceMapper({ configPath: options.config });
+    const mappings = mapper.getAllMappings();
+    if (mappings.length === 0) {
+        console.log('No mappings found.');
+        return;
+    }
+    const format = options.format.toLowerCase();
+    if (format === 'json') {
+        console.log(JSON.stringify(mappings, null, 2));
+    }
+    else if (format === 'yaml') {
+        console.log(yaml.dump(mappings));
+    }
+    else if (format === 'table') {
+        console.log('\nURL Mappings:\n');
+        mappings.forEach((mapping, index) => {
+            console.log(`${index + 1}. ${mapping.title}`);
+            console.log(`   URL:  ${mapping.url}`);
+            console.log(`   Path: ${mapping.localPath}`);
+            if (mapping.lastUpdated) {
+                console.log(`   Last Updated: ${mapping.lastUpdated}`);
+            }
+            console.log('');
+        });
+        console.log(`Total: ${mappings.length} mapping(s)`);
+    }
+    else {
+        console.error(`Error: Unsupported format '${options.format}'. Use 'table', 'json', or 'yaml'.`);
+        process.exit(1);
+    }
+});
+program
+    .command('validate')
+    .description('Validate all mappings in the configuration file')
+    .option('-c, --config <config>', 'Config file path', 'url-references.json')
+    .action((options) => {
+    const mapper = new UrlReferenceMapper_1.UrlReferenceMapper({ configPath: options.config });
+    const result = mapper.validate();
+    if (result.warnings.length > 0) {
+        console.log('\nWarnings:');
+        result.warnings.forEach(w => console.log(`  ⚠ [${w.type}] ${w.message}`));
+    }
+    if (result.errors.length > 0) {
+        console.log('\nErrors:');
+        result.errors.forEach(e => console.log(`  ✗ [${e.type}] ${e.message}`));
+        process.exit(1);
+    }
+    console.log('\n✓ All mappings are valid');
+});
+program
+    .command('export')
+    .description('Export mappings to different formats')
+    .option('-c, --config <config>', 'Config file path', 'url-references.json')
+    .option('-f, --format <format>', 'Export format (json, yaml, csv)', 'json')
+    .option('-o, --output <output>', 'Output file path (optional)')
+    .action((options) => {
+    const mapper = new UrlReferenceMapper_1.UrlReferenceMapper({ configPath: options.config });
+    const format = options.format;
+    try {
+        const output = mapper.export(format);
+        if (options.output) {
+            fs.writeFileSync(options.output, output, 'utf-8');
+            console.log(`✓ Exported to ${options.output}`);
+        }
+        else {
+            console.log(output);
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { UrlReferenceMapper } from './UrlReferenceMapper';
+export { UrlMapping, UrlReferenceMapperConfig, MapperConfig, ValidationResult, ValidationError, ValidationErrorType, ValidationWarning, ValidationWarningType, ExportFormat } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EACL,UAAU,EACV,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACb,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UrlReferenceMapper = void 0;
+var UrlReferenceMapper_1 = require("./UrlReferenceMapper");
+Object.defineProperty(exports, "UrlReferenceMapper", { enumerable: true, get: function () { return UrlReferenceMapper_1.UrlReferenceMapper; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAOA,2DAA0D;AAAjD,wHAAA,kBAAkB,OAAA"}

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+export interface UrlMapping {
+    title: string;
+    url: string;
+    localPath: string;
+    lastUpdated?: string;
+    metadata?: Record<string, any>;
+}
+export interface UrlReferenceMapperConfig {
+    configPath?: string;
+    mappings?: UrlMapping[];
+    autoSave?: boolean;
+    validateOnLoad?: boolean;
+    allowDuplicates?: boolean;
+}
+export type MapperConfig = UrlReferenceMapperConfig;
+export type ValidationErrorType = 'duplicate_url' | 'duplicate_path' | 'invalid_url' | 'missing_file' | 'invalid_format';
+export type ValidationWarningType = 'outdated_timestamp' | 'relative_path' | 'missing_metadata' | 'missing_file';
+export interface ValidationError {
+    type: ValidationErrorType;
+    message: string;
+    mapping?: UrlMapping;
+}
+export interface ValidationWarning {
+    type: ValidationWarningType;
+    message: string;
+    mapping?: UrlMapping;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+export type ExportFormat = 'json' | 'yaml' | 'csv';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,UAAU;IAEzB,KAAK,EAAE,MAAM,CAAC;IAEd,GAAG,EAAE,MAAM,CAAC;IAEZ,SAAS,EAAE,MAAM,CAAC;IAElB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAKD,MAAM,WAAW,wBAAwB;IAEvC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IAExB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAKD,MAAM,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAKpD,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,gBAAgB,CAAC;AAKrB,MAAM,MAAM,qBAAqB,GAC7B,oBAAoB,GACpB,eAAe,GACf,kBAAkB,GAClB,cAAc,CAAC;AAKnB,MAAM,WAAW,eAAe;IAE9B,IAAI,EAAE,mBAAmB,CAAC;IAE1B,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAKD,MAAM,WAAW,iBAAiB;IAEhC,IAAI,EAAE,qBAAqB,CAAC;IAE5B,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAKD,MAAM,WAAW,gBAAgB;IAE/B,KAAK,EAAE,OAAO,CAAC;IAEf,MAAM,EAAE,eAAe,EAAE,CAAC;IAE1B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAKD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@mytechtoday/url-reference-mapper",
+  "version": "1.0.0",
+  "description": "Bidirectional mapping between local filesystem paths and published internet URLs for Augment AI workflows",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "url-ref-mapper": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run lint && npm run test && npm run build",
+    "validate": "node dist/cli.js validate"
+  },
+  "keywords": [
+    "url-mapping",
+    "path-mapping",
+    "augment-ai",
+    "openspec",
+    "beads",
+    "url-reference",
+    "filesystem",
+    "wordpress",
+    "static-site",
+    "developer-tools"
+  ],
+  "author": "MyTech.Today",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mytech-today-now/url-reference.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mytech-today-now/url-reference/issues"
+  },
+  "homepage": "https://github.com/mytech-today-now/url-reference#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^11.0.0",
+    "js-yaml": "^4.1.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.50.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.0.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.3.3"
+  }
+}
+