feat(load)!: add opt-in network fallback for package specifiers (#12)

* feat(load): add opt-in network fallback for package specifiers

When local resolution fails for npm:/jsr: specifiers, Load() can now
fall back to fetching from unpkg.com CDN. This is opt-in via the new
Fetcher field on load.Options — nil (default) preserves existing
behavior with no network access.

This enables cem to delete its own loadFromNetwork() workaround and
rely entirely on load.Load() for both local and network resolution.

Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: code review

* fix: code review

* fix: code review

Author: bennypowers

load/fetch.go

@@ -0,0 +1,80 @@
+/*
+Copyright 2026 Benny Powers. All rights reserved.
+Use of this source code is governed by the GPLv3
+license that can be found in the LICENSE file.
+*/
+
+package load
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+
+	"bennypowers.dev/asimonim/internal/version"
+)
+
+const (
+	// DefaultTimeout is the maximum time to wait for a network fetch.
+	DefaultTimeout = 30 * time.Second
+
+	// DefaultMaxSize is the maximum allowed response size (10 MB).
+	DefaultMaxSize int64 = 10 * 1024 * 1024
+)
+
+// Fetcher fetches content from a URL.
+type Fetcher interface {
+	Fetch(ctx context.Context, url string) ([]byte, error)
+}
+
+// HTTPFetcher fetches content over HTTP with size limiting.
+type HTTPFetcher struct {
+	maxSize int64
+	client  *http.Client
+}
+
+// NewHTTPFetcher creates an HTTPFetcher with the given maximum response size.
+func NewHTTPFetcher(maxSize int64) *HTTPFetcher {
+	return &HTTPFetcher{
+		maxSize: maxSize,
+		client:  &http.Client{},
+	}
+}
+
+// Fetch fetches content from the given URL.
+func (f *HTTPFetcher) Fetch(ctx context.Context, url string) ([]byte, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("creating request for %s: %w", url, err)
+	}
+
+	req.Header.Set("User-Agent", "asimonim/"+version.Get())
+
+	resp, err := f.client.Do(req)
+	if err != nil {
+		if errors.Is(err, context.DeadlineExceeded) {
+			return nil, fmt.Errorf("timeout fetching %s: %w", url, err)
+		}
+		return nil, fmt.Errorf("fetching %s: %w", url, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("fetching %s: %s", url, resp.Status)
+	}
+
+	limitedReader := io.LimitReader(resp.Body, f.maxSize+1)
+	content, err := io.ReadAll(limitedReader)
+	if err != nil {
+		return nil, fmt.Errorf("reading response from %s: %w", url, err)
+	}
+
+	if int64(len(content)) > f.maxSize {
+		return nil, fmt.Errorf("response from %s exceeds maximum size of %d bytes", url, f.maxSize)
+	}
+
+	return content, nil
+}

load/fetch_test.go

@@ -0,0 +1,88 @@
+/*
+Copyright 2026 Benny Powers. All rights reserved.
+Use of this source code is governed by the GPLv3
+license that can be found in the LICENSE file.
+*/
+
+package load
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestHTTPFetcher_Success(t *testing.T) {
+	body := `{"color": {"$value": "#fff", "$type": "color"}}`
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(body))
+	}))
+	defer srv.Close()
+
+	f := NewHTTPFetcher(DefaultMaxSize)
+	content, err := f.Fetch(context.Background(), srv.URL+"/tokens.json")
+	if err != nil {
+		t.Fatalf("Fetch() error = %v", err)
+	}
+	if string(content) != body {
+		t.Errorf("Fetch() = %q, want %q", string(content), body)
+	}
+}
+
+func TestHTTPFetcher_Timeout(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(200 * time.Millisecond)
+		_, _ = w.Write([]byte("too late"))
+	}))
+	defer srv.Close()
+
+	f := NewHTTPFetcher(DefaultMaxSize)
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+
+	_, err := f.Fetch(ctx, srv.URL+"/tokens.json")
+	if err == nil {
+		t.Fatal("expected timeout error")
+	}
+	if !strings.Contains(err.Error(), "timeout") && !strings.Contains(err.Error(), "context deadline exceeded") {
+		t.Errorf("expected timeout error, got: %v", err)
+	}
+}
+
+func TestHTTPFetcher_MaxSizeExceeded(t *testing.T) {
+	// Response is 100 bytes, limit to 50
+	body := strings.Repeat("x", 100)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(body))
+	}))
+	defer srv.Close()
+
+	f := NewHTTPFetcher(50)
+	_, err := f.Fetch(context.Background(), srv.URL+"/tokens.json")
+	if err == nil {
+		t.Fatal("expected max size error")
+	}
+	if !strings.Contains(err.Error(), "exceeds maximum size") {
+		t.Errorf("expected max size error, got: %v", err)
+	}
+}
+
+func TestHTTPFetcher_Non200Status(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "not found", http.StatusNotFound)
+	}))
+	defer srv.Close()
+
+	f := NewHTTPFetcher(DefaultMaxSize)
+	_, err := f.Fetch(context.Background(), srv.URL+"/tokens.json")
+	if err == nil {
+		t.Fatal("expected error for 404")
+	}
+	if !strings.Contains(err.Error(), "404") {
+		t.Errorf("expected 404 in error, got: %v", err)
+	}
+}

load/load.go

@@ -8,8 +8,11 @@ license that can be found in the LICENSE file.
 package load
 
 import (
+	"context"
+	"errors"
 	"fmt"
 	"path/filepath"
+	"time"
 
 	"bennypowers.dev/asimonim/config"
 	"bennypowers.dev/asimonim/fs"
@@ -20,6 +23,14 @@ import (
 	"bennypowers.dev/asimonim/token"
 )
 
+var (
+	// ErrLocalResolution indicates that local filesystem resolution failed.
+	ErrLocalResolution = errors.New("local resolution failed")
+
+	// ErrNetworkFallback indicates that the CDN network fallback also failed.
+	ErrNetworkFallback = errors.New("network fallback failed")
+)
+
 // Options configures how tokens are loaded.
 type Options struct {
 	// Root is the directory for local specifier resolution (required for local/npm: paths).
@@ -39,6 +50,16 @@ type Options struct {
 	// SchemaVersion overrides auto-detection from file content.
 	// Takes precedence over config file if set.
 	SchemaVersion schema.Version
+
+	// Fetcher enables opt-in network fallback for npm: specifiers.
+	// When set, if local resolution fails for an npm: specifier,
+	// Load will attempt to fetch the content from unpkg.com.
+	// Nil means no network fallback (default).
+	Fetcher Fetcher
+
+	// FetchTimeout is the maximum time to wait for a network fetch.
+	// Defaults to DefaultTimeout when zero. Has no effect if Fetcher is nil.
+	FetchTimeout time.Duration
 }
 
 // Load loads design tokens from a specifier with full resolution.
@@ -48,16 +69,19 @@ type Options struct {
 //   - npm package: "npm:@scope/pkg/tokens.json" (requires node_modules)
 //   - jsr package: "jsr:@scope/pkg/tokens.json" (requires node_modules)
 //
+// When Options.Fetcher is set, npm: specifiers that fail local resolution
+// will fall back to fetching from unpkg.com.
+//
 // The loading process:
 //  1. Optionally loads config from .config/design-tokens.yaml
 //  2. Applies Options values (they take precedence over config)
-//  3. Resolves specifier to file content via filesystem
+//  3. Resolves specifier to file content via filesystem (with optional CDN fallback)
 //  4. Detects schema version (if not specified)
 //  5. Parses tokens
 //  6. Resolves $extends (v2025.10)
 //  7. Resolves aliases
 //  8. Returns *token.Map
-func Load(spec string, opts Options) (*token.Map, error) {
+func Load(ctx context.Context, spec string, opts Options) (*token.Map, error) {
 	// Set up filesystem
 	filesystem := opts.FS
 	if filesystem == nil {
@@ -97,7 +121,11 @@ func Load(spec string, opts Options) (*token.Map, error) {
 	}
 
 	// Resolve specifier to content
-	content, err := resolveContent(spec, root, filesystem)
+	fetchTimeout := opts.FetchTimeout
+	if fetchTimeout == 0 {
+		fetchTimeout = DefaultTimeout
+	}
+	content, err := resolveContent(ctx, spec, root, filesystem, opts.Fetcher, fetchTimeout)
 	if err != nil {
 		return nil, fmt.Errorf("failed to resolve specifier %q: %w", spec, err)
 	}
@@ -136,8 +164,10 @@ func Load(spec string, opts Options) (*token.Map, error) {
 	return token.NewMap(tokens, prefix), nil
 }
 
-// resolveContent resolves a specifier to file content via filesystem.
-func resolveContent(spec, root string, filesystem fs.FileSystem) ([]byte, error) {
+// resolveContent resolves a specifier to file content.
+// Tries local resolution first. If that fails and a Fetcher is provided,
+// falls back to CDN for npm: specifiers.
+func resolveContent(ctx context.Context, spec, root string, filesystem fs.FileSystem, fetcher Fetcher, fetchTimeout time.Duration) ([]byte, error) {
 	// Create resolver chain
 	res, err := specifier.NewDefaultResolver(filesystem, root)
 	if err != nil {
@@ -147,7 +177,8 @@ func resolveContent(spec, root string, filesystem fs.FileSystem) ([]byte, error)
 	// Resolve specifier to path
 	resolved, err := res.Resolve(spec)
 	if err != nil {
-		return nil, err
+		// Local resolution failed — try CDN fallback
+		return fetchFromCDN(ctx, spec, fetcher, fetchTimeout, err)
 	}
 
 	// Make local paths absolute relative to root
@@ -157,9 +188,36 @@ func resolveContent(spec, root string, filesystem fs.FileSystem) ([]byte, error)
 	}
 
 	// Read file content
-	content, err := filesystem.ReadFile(path)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read %s: %w", path, err)
+	content, readErr := filesystem.ReadFile(path)
+	if readErr != nil {
+		// File read failed — try CDN fallback (npm: specifiers only;
+		// non-npm specifiers return localErr unchanged via CDNURL check)
+		localErr := fmt.Errorf("failed to read %s: %w", path, readErr)
+		return fetchFromCDN(ctx, spec, fetcher, fetchTimeout, localErr)
+	}
+
+	return content, nil
+}
+
+// fetchFromCDN attempts to fetch content from CDN as a fallback.
+// Returns the original localErr if no fetcher is provided or the specifier
+// has no CDN URL.
+func fetchFromCDN(ctx context.Context, spec string, fetcher Fetcher, fetchTimeout time.Duration, localErr error) ([]byte, error) {
+	if fetcher == nil {
+		return nil, localErr
+	}
+
+	cdnURL, ok := specifier.CDNURL(spec)
+	if !ok {
+		return nil, localErr
+	}
+
+	ctx, cancel := context.WithTimeout(ctx, fetchTimeout)
+	defer cancel()
+
+	content, fetchErr := fetcher.Fetch(ctx, cdnURL)
+	if fetchErr != nil {
+		return nil, fmt.Errorf("%w (%w), %w: %w", ErrLocalResolution, localErr, ErrNetworkFallback, fetchErr)
 	}
 
 	return content, nil