capdag 0.88.20458

package/README.md

@@ -0,0 +1,131 @@
+# Cap URN - JavaScript Implementation
+
+JavaScript implementation of Cap URN (Capability Uniform Resource Names), built on [Tagged URN](https://github.com/machinefabric/tagged-urn-js).
+
+## Features
+
+- **Required Direction Specifiers** - `in`/`out` tags for input/output media types
+- **Media URN Validation** - Validates direction spec values are valid Media URNs
+- **Special Pattern Values** - `*` (must-have-any), `?` (unspecified), `!` (must-not-have)
+- **Graded Specificity** - Exact values score higher than wildcards
+- **Cross-Language Compatible** - Identical behavior to Rust, Go, and Objective-C implementations
+- **Production Ready** - No fallbacks, fails hard on invalid input
+
+## Installation
+
+```bash
+npm install capdag
+```
+
+## Quick Start
+
+```javascript
+const { CapUrn, CapUrnBuilder, CapMatcher } = require('capdag');
+
+// Create from string (with required direction specifiers)
+const cap = CapUrn.fromString('cap:in="media:binary";op=extract;out="media:object"');
+console.log(cap.toString());
+
+// Use builder pattern
+const built = new CapUrnBuilder()
+  .inSpec('media:void')
+  .outSpec('media:object')
+  .tag('op', 'generate')
+  .tag('target', 'thumbnail')
+  .build();
+
+// Matching
+const request = CapUrn.fromString('cap:in="media:binary";op=extract;out="media:object"');
+console.log(cap.accepts(request)); // true
+
+// Find best match by specificity
+const caps = [
+  CapUrn.fromString('cap:in=*;op=extract;out=*'),
+  CapUrn.fromString('cap:in="media:binary";op=extract;out="media:object"'),
+  CapUrn.fromString('cap:ext=pdf;in="media:binary";op=extract;out="media:object"')
+];
+const best = CapMatcher.findBestMatch(caps, request);
+console.log(best.toString()); // Most specific match
+```
+
+## API Reference
+
+### CapUrn Class
+
+#### Static Methods
+- `CapUrn.fromString(s)` - Parse Cap URN from string
+  - Throws `CapUrnError` on invalid format or missing direction specifiers
+
+#### Instance Methods
+- `toString()` - Get canonical string representation
+- `getTag(key)` - Get tag value (case-insensitive)
+- `getInSpec()` - Get input media type
+- `getOutSpec()` - Get output media type
+- `hasTag(key, value)` - Check if tag exists with value
+- `withTag(key, value)` - Add/update tag (returns new instance)
+- `withoutTag(key)` - Remove tag (returns new instance)
+- `accepts(request)` - Check if this cap (as pattern) accepts a request
+- `specificity()` - Get specificity score for matching
+- `isMoreSpecificThan(other)` - Compare specificity
+- `equals(other)` - Check equality
+
+### CapUrnBuilder Class
+
+Fluent builder for constructing Cap URNs:
+
+```javascript
+const cap = new CapUrnBuilder()
+  .inSpec('media:binary')
+  .outSpec('media:object')
+  .tag('op', 'extract')
+  .tag('target', 'metadata')
+  .build();
+```
+
+### CapMatcher Class
+
+Utility for matching sets of caps:
+
+- `CapMatcher.findBestMatch(caps, request)` - Find most specific match
+- `CapMatcher.findAllMatches(caps, request)` - Find all matches (sorted by specificity)
+
+### Error Handling
+
+```javascript
+const { CapUrnError, ErrorCodes } = require('capdag');
+
+try {
+  const cap = CapUrn.fromString('cap:op=extract'); // Missing in/out
+} catch (error) {
+  if (error instanceof CapUrnError) {
+    console.log(`Error code: ${error.code}`); // MISSING_IN_SPEC
+  }
+}
+```
+
+Cap-specific error codes:
+- `ErrorCodes.MISSING_IN_SPEC` - Missing required `in` tag
+- `ErrorCodes.MISSING_OUT_SPEC` - Missing required `out` tag
+- `ErrorCodes.INVALID_MEDIA_URN` - Invalid Media URN in direction spec
+
+For base Tagged URN error codes, see [Tagged URN documentation](https://github.com/machinefabric/tagged-urn-js).
+
+## Documentation
+
+- [RULES.md](./RULES.md) - Cap-specific rules
+- [Tagged URN RULES.md](https://github.com/machinefabric/tagged-urn-js/blob/main/RULES.md) - Base format rules (case, quoting, wildcards, etc.)
+
+## Testing
+
+```bash
+npm test
+```
+
+## Cross-Language Compatibility
+
+This JavaScript implementation produces identical results to:
+- [Rust reference implementation](https://github.com/machinefabric/capdag)
+- [Go implementation](https://github.com/machinefabric/capdag-go)
+- [Objective-C implementation](https://github.com/machinefabric/capdag-objc)
+
+All implementations pass the same test cases and follow identical rules.

package/RULES.md

@@ -0,0 +1,111 @@
+# Cap URN Rules (JavaScript)
+
+## Overview
+
+Cap URNs extend Tagged URNs with capability-specific requirements. For base Tagged URN format rules (case handling, tag ordering, special values, quoting, value-less tags, etc.), see [Tagged URN RULES.md](https://github.com/machinefabric/tagged-urn-js/blob/main/RULES.md).
+
+This document covers only cap-specific rules.
+
+## Cap-Specific Rules
+
+### 1. Required Direction Specifiers
+
+Cap URNs **must** include `in` and `out` tags that specify input/output media types:
+
+```javascript
+// Valid cap URN with direction specifiers
+const cap = CapUrn.fromString('cap:in="media:binary";op=extract;out="media:object"');
+
+// Invalid - missing direction specifiers
+CapUrn.fromString('cap:op=extract'); // throws ErrorCodes.MISSING_IN_SPEC
+```
+
+### 2. Media URN Validation
+
+Direction specifier values must be valid Media URNs or special pattern values:
+
+```javascript
+// Valid: Media URN value
+'cap:in="media:binary";op=extract;out="media:object"'
+
+// Valid: Must-have-any (any media type)
+'cap:in=*;op=extract;out=*'
+
+// Invalid: Not a Media URN or special value
+'cap:in=binary;op=extract;out=object' // throws ErrorCodes.INVALID_MEDIA_URN
+```
+
+### 3. Matching Semantics
+
+Cap matching uses Tagged URN matching semantics:
+
+| Pattern Value | Meaning | Instance Missing | Instance=v | Instance=x≠v |
+|---------------|---------|------------------|------------|--------------|
+| (missing) | No constraint | OK | OK | OK |
+| `K=?` | No constraint (explicit) | OK | OK | OK |
+| `K=!` | Must-not-have | OK | NO | NO |
+| `K=*` | Must-have, any value | NO | OK | OK |
+| `K=v` | Must-have, exact value | NO | OK | NO |
+
+### 4. Graded Specificity
+
+Specificity uses graded scoring:
+
+| Value Type | Score |
+|------------|-------|
+| Exact value (K=v) | 3 |
+| Must-have-any (K=*) | 2 |
+| Must-not-have (K=!) | 1 |
+| Unspecified (K=?) or missing | 0 |
+
+Examples:
+- `cap:in="media:binary";op=extract;out="media:object"` → 3+3+3 = 9
+- `cap:in=*;op=extract;out=*` → 2+3+2 = 7
+
+## Cap-Specific Error Codes
+
+| Code | Name | Description |
+|------|------|-------------|
+| 10 | MISSING_IN_SPEC | Cap URN missing required `in` tag |
+| 11 | MISSING_OUT_SPEC | Cap URN missing required `out` tag |
+| 12 | INVALID_MEDIA_URN | Direction spec value is not a valid Media URN |
+
+## Validation Rules
+
+### XV5: No Redefinition of Registry Media Specs
+
+Inline media specs in a capability's `media_specs` table must not redefine media specs that already exist in the global registry or built-in specs.
+
+```javascript
+const { validateNoMediaSpecRedefinitionSync, MEDIA_STRING } = require('capdag');
+
+// This will fail - MEDIA_STRING is a built-in spec
+const mediaSpecs = {
+  [MEDIA_STRING]: { media_type: 'text/plain', title: 'My String' }
+};
+const result = validateNoMediaSpecRedefinitionSync(mediaSpecs);
+// result: { valid: false, error: 'XV5: ...', redefines: ['media:textable'] }
+
+// This is allowed - custom spec that doesn't exist
+const customSpecs = {
+  'media:my-custom-type': { media_type: 'application/json', title: 'My Type' }
+};
+const customResult = validateNoMediaSpecRedefinitionSync(customSpecs);
+// result: { valid: true }
+```
+
+For server-side validation with registry access, use the async version:
+```javascript
+const { validateNoMediaSpecRedefinition } = require('capdag');
+
+const result = await validateNoMediaSpecRedefinition(mediaSpecs, {
+  registryLookup: async (urn) => await mediaStore.get(urn) !== null
+});
+```
+
+## Cross-Language Compatibility
+
+This JavaScript implementation follows the same rules as:
+- [Rust reference implementation](https://github.com/machinefabric/capdag)
+- [Go implementation](https://github.com/machinefabric/capdag-go)
+- [Objective-C implementation](https://github.com/machinefabric/capdag-objc)