ior-resolver/README.md

# @metatrom/ior-resolver

IOR (Interoperable Object Reference) resolver for Metro bundler and Node.js with support for local and remote component fetching.

## Features

- 🚀 **Metro Bundler Support** - Seamlessly integrate IOR resolution with React Native projects
- 🌐 **Remote Component Fetching** - Load components from GitHub, Gitea, IPFS, and P2P networks
- 📦 **Local Component Resolution** - Resolve local components using package.json metadata
- 🔄 **Hot Reload Support** - Automatic mapping updates during development
- 📝 **TypeScript Support** - Auto-generate type declarations for IOR components
- ⚡ **Caching** - Intelligent caching of remote components for better performance
- 🛠️ **Pre-build Script** - Generate types before development starts
- 🎯 **Shared Core** - Consolidated functions to avoid duplication

## Installation

```bash
npm install @metatrom/ior-resolver
```

## Project Structure

```
@metatrom/ior-resolver/
├── bin/                      # Executable scripts
│   ├── prebuild-ior-types.js   # Pre-build script for type generation
│   └── NodeImportLoader.ts      # Node.js loader implementation
├── lib/                      # Core library files
│   ├── ior-core.js             # Shared core functions
│   ├── metro-ior-resolver.js   # Metro resolver implementation
│   └── fetch-remote-component.js # Remote fetching utility
├── index.js                  # Main entry point
├── index.d.ts               # TypeScript definitions
└── package.json
```

## Usage

### Metro Configuration (React Native)

In your `metro.config.js`:

```javascript
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const { createHotReloadableResolver } = require('@metatrom/ior-resolver');

const defaultConfig = getDefaultConfig(__dirname);

const config = {
  resolver: {
    resolveRequest: createHotReloadableResolver(__dirname),
  },
};

module.exports = mergeConfig(defaultConfig, config);
```

### Node.js Loader

For Node.js projects using TypeScript and IOR imports:

```javascript
// In your loader file
import { resolve, load } from '@metatrom/ior-resolver/node';

// Or register the loader
import { register } from 'node:module';
import { pathToFileURL } from 'node:url';

register('@metatrom/ior-resolver/node', pathToFileURL('./'));
```

### Pre-build Script

Add to your `package.json` scripts to generate TypeScript declarations before development:

```json
{
  "scripts": {
    "prebuild": "prebuild-ior-types",
    "dev": "npm run prebuild && npm start"
  }
}
```

Or run directly:

```bash
npx prebuild-ior-types
```

## IOR Format

IOR (Interoperable Object Reference) provides a unified way to reference components across different sources:

### Local Components
```javascript
import Logger from 'ior:esm:com.metatrom.examples.logger@1.0.0';
```

### Remote Components

#### GitHub
```javascript
import Component from 'ior:github:owner/repo:componentname@version';
```

#### Gitea
```javascript
import Component from 'ior:gitea:instance.com:owner/repo:componentname@version';
// Alternative format for repos with slashes in name:
import Component from 'ior:gitea:instance.com:owner/repo/componentname@version';
```

#### IPFS
```javascript
import Component from 'ior:ipfs:QmHash:componentname@version';
```

#### P2P (Coming Soon)
```javascript
import Component from 'ior:p2p:peer-id:componentname@version';
```

## Component Structure

Local components should follow this structure:

```
src/components/
└── componentname/
    └── version/
        ├── package.json
        ├── index.ts (or componentname.ts)
        └── componentname.d.ts (optional)
```

### package.json Example

```json
{
  "name": "logger",
  "version": "1.0.0",
  "main": "index.ts",
  "metatrom": {
    "ior": "com.metatrom.examples.logger@1.0.0"
  }
}
```

## API Reference

### Core Functions (ior-core.js)

The shared core module provides common functionality used by both Metro and Node.js implementations:

- `parseRemoteIOR(ior)` - Parse remote IOR strings
- `parsePackageJson(path)` - Synchronously parse package.json
- `parsePackageJsonAsync(path)` - Asynchronously parse package.json
- `fetchUrl(url)` - Fetch content from URL
- `fetchUrlBuffer(url)` - Fetch URL as Buffer
- `fetchFromGitHub(config)` - Fetch from GitHub
- `fetchFromGitea(config)` - Fetch from Gitea
- `fetchFromIPFS(config)` - Fetch from IPFS
- `extractArchive(buffer, dir)` - Extract tar.gz archives
- `findEntryPoint(dir, name)` - Find component entry point
- `generateCacheHash(ior)` - Generate SHA256 hash for caching
- `buildLocalIORMappings(root)` - Build local component mappings

### Metro Resolver Functions

#### `createIORResolver(projectRoot: string)`
Creates a basic IOR resolver for Metro.

#### `createHotReloadableResolver(projectRoot: string)`
Creates an IOR resolver with hot reload support that watches for package.json changes.

#### `fetchRemoteComponent(ior: string)`
Fetches and caches a remote component.

#### `clearRemoteCache()`
Clears all cached remote components.

### Node.js Loader Functions

#### `resolve(specifier, context, defaultResolve)`
Node.js loader resolve hook for IOR imports.

#### `load(url, context, defaultLoad)`
Node.js loader load hook for TypeScript transpilation.

#### `clearCache(ior?: string)`
Clears cache for a specific IOR or all cached components.

#### `setCacheTTL(ttl: number)`
Sets the cache time-to-live for remote components.

#### `preloadComponent(ior: string)`
Pre-fetches a remote component for faster access.

## Configuration

### Environment Variables

- `DEBUG=true` - Enable debug logging for the Node.js loader
- `NODE_ENV=development` - Enable hot reload for Metro resolver

### Cache Configuration

The resolver uses different cache locations for different environments:

- **Metro**: `.ior-cache/remote/` in project root
- **Node.js**: OS temp directory under `metatrom-components/remote/`
- **Default TTL**: 1 hour (3600000ms)

### Cache Persistence

Metro resolver maintains a persistent cache mapping in `.ior-cache/mappings.json` for faster startup times.

## Architecture

The package is designed with a shared core architecture:

1. **ior-core.js** - Contains all shared functionality for parsing, fetching, and caching
2. **metro-ior-resolver.js** - Metro-specific implementation using the shared core
3. **NodeImportLoader.ts** - Node.js-specific implementation using the shared core

This design eliminates code duplication and ensures consistency across different environments.

## Migration from Direct Implementation

If you're migrating from having these files directly in your project:

1. Install the package:
   ```bash
   npm install @metatrom/ior-resolver
   ```

2. Update `metro.config.js` to use the package import:
   ```javascript
   const { createHotReloadableResolver } = require('@metatrom/ior-resolver');
   ```

3. Update `package.json` scripts:
   ```json
   {
     "scripts": {
       "prebuild": "prebuild-ior-types"
     }
   }
   ```

4. Remove the old files from your project:
   - `metro-ior-resolver.js`
   - `scripts/prebuild-ior-types.js`
   - `fetch-remote-component.js`
   - `NodeImportLoader.ts`

## TypeScript Support

The package automatically generates TypeScript declarations for IOR components:

- Local components: Types are read from `.d.ts` files in the component directory
- Remote components: Types are fetched from the remote repository
- Auto-generated types are saved to `src/types/auto-generated.d.ts`

## Security Considerations

- Remote components are fetched over HTTPS
- Components are cached locally with SHA256 hash verification
- Cache TTL ensures components are refreshed periodically
- No automatic code execution - components must be explicitly imported

## Performance

- **Caching**: Components are cached locally to avoid repeated network requests
- **Parallel fetching**: Multiple components can be fetched in parallel
- **Hot reload**: Development mode watches for changes without restart
- **Type generation**: Types are generated asynchronously without blocking

## Troubleshooting

### Common Issues

1. **"Cannot resolve IOR module"**
   - Ensure the component exists in the expected location
   - Check the IOR format is correct
   - Verify network connectivity for remote components

2. **"Failed to fetch remote component"**
   - Check network connectivity
   - Verify the repository exists and is accessible
   - Ensure the version tag exists

3. **Types not generating**
   - Run `npx prebuild-ior-types` manually
   - Check for `.d.ts` files in component directories
   - Verify `src/types/` directory exists

### Debug Mode

Enable debug logging:

```bash
DEBUG=true npm start
```

### Clear Cache

If you encounter stale cache issues:

```javascript
// In your code
const { clearRemoteCache } = require('@metatrom/ior-resolver');
clearRemoteCache();
```

Or manually delete:
```bash
rm -rf .ior-cache
rm -rf /tmp/metatrom-components  # Node.js cache
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### Development Setup

1. Clone the repository
2. Install dependencies: `npm install`
3. Build TypeScript: `npm run build`
4. Run tests: `npm test`

### Code Structure

- Keep shared functionality in `lib/ior-core.js`
- Environment-specific code in respective files
- Maintain TypeScript types for all exports
- Follow existing code style

## License

MIT

## TODO: Missing Features

The following features are documented in `docs/IOR_RESOLVER.md` but not yet implemented in the codebase:

### High Priority
- [ ] **Authentication for Private Repositories**
  - [ ] GitHub authentication via `GITHUB_TOKEN` environment variable
  - [ ] Gitea authentication with instance-specific tokens
  - [ ] Add Authorization headers to fetch requests
  - *Impact: Currently cannot access private repositories*

- [ ] **Error Recovery & Resilience**
  - [ ] Implement retry logic with exponential backoff for network failures
  - [ ] Add `IORResolutionError` class for better error categorization
  - [ ] Implement fallback strategies for failed fetches
  - *Impact: Single network failures cause immediate errors*

### Medium Priority
- [ ] **Security Enhancements**
  - [ ] HTTPS certificate validation for Git sources
  - [ ] Content sanitization and pattern scanning
  - [ ] Component signature verification
  - [ ] Sandboxing options with configurable restrictions:
    - Allowed protocols whitelist
    - Allowed domains whitelist
    - Maximum component size limits
  - *Impact: Limited security validation of fetched components*

### Low Priority
- [ ] **Advanced Features**
  - [ ] Per-source cache TTL configuration
  - [ ] Component dependency resolution
  - [ ] Version conflict resolution
  - [ ] Cross-platform compatibility checks
  - [ ] Progress reporting for large downloads

### Future Roadmap (from docs)
- [ ] P2P protocol implementation (libp2p)
- [ ] Decentralized component registry
- [ ] Smart contract integration for Web3
- [ ] Component marketplace
- [ ] AI-assisted component discovery

## Support

For issues and feature requests, please use the [GitHub issue tracker](https://github.com/metatrom/ior-resolver/issues).