Bidirectional mapping between local filesystem paths and published internet URLs for Augment AI workflows
npm install @mytechtoday/url-reference-mapperBidirectional mapping between local filesystem paths and published internet URLs for Augment AI workflows.


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
``bash`
npm install @mytechtoday/url-reference
`bash`
npx url-ref-mapper init
This creates a url-references.json file with seed data for 4 copper mining blog posts.
`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();
`
#### Constructor
`typescript`
new UrlReferenceMapper(config?: UrlReferenceMapperConfig)
Config Options:
- configPath?: string - Path to JSON/YAML configuration filemappings?: UrlMapping[]
- - Inline mappings for testingautoSave?: 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
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.
`typescript
interface UrlMapping {
title: string;
url: string;
localPath: string;
lastUpdated?: string;
}
interface ValidationResult {
valid: boolean;
errors: string[];
warnings: string[];
}
type ExportFormat = 'json' | 'yaml' | 'csv';
`
`bash`
npx url-ref-mapper init
npx url-ref-mapper init --format yaml --path custom-path.yaml
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"
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"
`bash`
npx url-ref-mapper get-path "https://example.com/post/"
`bash`
npx url-ref-mapper validate
`bash`
npx url-ref-mapper export --format csv --output mappings.csv
npx url-ref-mapper export --format yaml
`bashShow confirmation prompt
npx url-ref-mapper uninstall
$3
Update the CLI to the latest version from npm.`bash
Update local installation
npx url-ref-mapper self-updateUpdate global installation
url-ref-mapper self-update --global
`$3
Display the current version of the URL reference mapper.`bash
Show version information
npx url-ref-mapper versionOr use the --version flag
npx url-ref-mapper --version
`๐ค Augment AI Integration
This package is designed to work seamlessly with Augment AI workflows:
$3
Reference the package in your spec files:
`markdown
Use @mytechtoday/url-reference to resolve local paths to published URLs.
`$3
`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' });
`$3
This package works alongside
@mytechtoday/augment-extensions:`bash
Install both
npm install -g @mytechtoday/augment-extensions
npm install @mytechtoday/url-referenceUse together in your project
augx link coding-standards/typescript
`๐ Configuration File Format
$3
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"
}
]
`$3
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.
$3
Windows:
- Use backslashes:
C:\projects\blog\post.html
- Or forward slashes: C:/projects/blog/post.html
- Both formats are supported and normalized internallymacOS/Linux:
- Use forward slashes:
/home/user/projects/blog/post.html
- Absolute paths recommended for consistency$3
Windows (PowerShell):
`powershell
Initialize config
npx url-ref-mapper initAdd mapping
npx url-ref-mapper add
--url "https://example.com/post/" macOS/Linux (Bash/Zsh):
`bash
Initialize config
npx url-ref-mapper initAdd 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-referenceInstall dependencies
npm installBuild
npm run buildRun in development mode
npm run devLint
npm run lint
npm run lint:fixFormat
npm run format
`๐ฆ Publishing
`bash
Build and test
npm run build
npm testPublish 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`)MIT License - see LICENSE file for details.
- Augment Code AI - AI coding assistant
- OpenSpec - Spec-driven development
- Beads - Distributed issue tracker
- Augment Extensions - Extension modules for Augment AI
- Issues: GitHub Issues
- Discussions: GitHub Discussions
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