OpenAgentsControl/.opencode/context/openagents-repo/guides/resolving-installer-wildcard-failures.md

Guide: Resolving Installer Wildcard Failures

Purpose: Capture the root cause, fix, and lessons from wildcard context install failures.

Last Updated: 2026-01-12

---

Prerequisites

• Installer changes scoped to install.sh
• Registry entries validated (./scripts/registry/validate-registry.sh)

Estimated time: 10 min

Steps

1. Identify the failure mode

Symptom:

curl: (3) URL rejected: Malformed input to a URL function

Cause: Wildcard expansion returned context IDs that weren’t path-aligned (e.g., standards-code mapped to .opencode/context/core/standards/code-quality.md). Installer treated IDs as paths.

2. Expand wildcards to path-based IDs

Goal: Make wildcard expansion output core/... IDs that map directly to a path.

Update:

• Expand context:core/* to core/standards/code-quality style IDs

3. Resolve context paths deterministically

Goal: Avoid ambiguous matches and ensure one registry entry is used.

Update:

• Add resolve_component_path to map context IDs to the registry path
• Use first(...) in jq queries for deterministic selection

4. Verify installation

bash scripts/tests/test-e2e-install.sh

Expected: All E2E tests pass on macOS and Ubuntu.

Verification

REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list

Troubleshooting

Issue	Solution
Malformed input to a URL function	Ensure wildcard expansion returns core/... IDs and uses resolve_component_path
Multiple context entries for one path	Use first(...) in jq lookups

Related

• guides/debugging.md
• guides/updating-registry.md
• core-concepts/registry.md