013682c499
* fix: ContextScout falls back to global core/ when local core/ missing Users who install OAC globally have core standards at ~/.config/opencode/context/core/ but no local core/ directory. ContextScout now does a one-time check on startup: if local core/navigation.md doesn't exist, it checks the global path from paths.json. This resolves the ENOENT errors when agents try to read core/standards/ files that only exist globally. - paths.json: enabled global path (~/.config/opencode/context) - contextscout.md: added global_fallback rule with 2-glob cap - Fallback is ONLY for core/ files, never project-intelligence * docs: add context resolution explanation to README Explains how ContextScout resolves context files: local-first, global fallback only for core/ files, project-intelligence always local. Includes flow diagram, key rules, and common setup table. * fix: resolve installer failures and add comprehensive validation ## Summary Fixes critical installer failures where ContextScout and other components couldn't find their configuration files after installation. Adds comprehensive validation system to prevent future issues. ## Problems Fixed ### 1. Missing Critical Files (13 dead registry references) Files were referenced in registry but didn't exist on disk: - workflows-delegation (split into 3 files) - design-iteration (split into 8 files) - animation-patterns (split into 6 files) - adding-agent (split into 2 files) - adding-skill (split into 3 files) - navigation-design (split into 2 files) - external-libraries (split into 3 files) - claude-code-docs/* (directory removed) ### 2. Missing Infrastructure Files ContextScout failed after installation because 2 critical files weren't in registry: - paths.json - Context root configuration - navigation.md - Root navigation for discovery ### 3. Profile Inconsistencies Profiles referenced components that don't exist: - context:adding-skill → context:adding-skill-basics - context:animation-patterns → animation-basics/components/advanced - context:design-assets (removed - doesn't exist) - context:to-be-consumed/* (removed - directory doesn't exist) - skill:context-manager → subagent:context-manager ## Changes Made ### Registry (registry.json) - Removed 13 dead references - Added 27 new split-file entries - Added 2 critical infrastructure entries - Fixed all 5 profile configurations - Updated ContextScout dependencies - Updated agent-metadata.json dependencies ### New Validation Scripts - scripts/registry/check-dependencies.ts - Comprehensive dependency checker - scripts/tests/test-installer-files.sh - Installer simulation test - scripts/registry/fix-registry.py - Automated registry fixer - scripts/hooks/pre-commit - Git pre-commit hook ### Documentation - docs/maintenance/REGISTRY_FIXES_SUMMARY.md - docs/maintenance/CONTEXTSCOUT_FIX.md - docs/maintenance/REGISTRY_VALIDATION.md ## Validation Results Before: - 13 missing files in registry - 78 orphaned files on disk - 3 missing dependencies - Installer would fail After: - 244 total paths, 0 missing - 262 dependency checks, 0 failures - 0 orphaned dependencies - All profiles consistent - Installer works correctly ## Testing ```bash # Registry validation bun run scripts/registry/validate-registry.ts # ✓ All 244 paths valid # Dependency checking bun run scripts/registry/check-dependencies.ts # ✓ All 262 checks passed # Installer test ./scripts/tests/test-installer-files.sh --local --profile=essential # ✓ All files accessible ``` ## Usage ### Run validation before commits: ```bash bun run scripts/registry/check-dependencies.ts ``` ### Install pre-commit hook: ```bash cp scripts/hooks/pre-commit .git/hooks/pre-commit chmod +x .git/hooks/pre-commit ``` ### Test installer: ```bash ./scripts/tests/test-installer-files.sh --local --profile=essential ``` ## Impact This fix ensures: - ✓ Installer downloads all required files - ✓ ContextScout works immediately after install - ✓ No broken dependencies - ✓ No missing profile components - ✓ Future issues caught by validation ## Breaking Changes None - all changes are additive or fix broken references. ## Related - Fixes: ContextScout failing after installation - Prevents: Missing file errors during install - Adds: Comprehensive validation system * fix: resolve shellcheck warnings in test scripts - Remove unused REPO_URL variable from test-installer-files.sh - Add shellcheck disable comments for cleanup functions used via trap - Fixes CI failures in ShellCheck Analysis workflow * fix: resolve shellcheck errors across all scripts Fixed arithmetic expansion issues and code quality warnings: - Changed ((var++)) to POSIX-compliant 1 syntax - Fixed unquoted variables and grep pipe issues (SC2002, SC2143) - Added shellcheck disable comments for intentional patterns - Fixed variable initialization and return statement placement Scripts fixed: - scripts/tests/*.sh (5 files) - scripts/registry/*.sh (4 files) - scripts/validation/*.sh (2 files) - scripts/*.sh (2 files) - evals/framework/scripts/*.sh (2 files) All scripts now pass shellcheck --severity=warning * chore: trigger CI shellcheck validation
181 lines
6.2 KiB
Markdown
181 lines
6.2 KiB
Markdown
# Installer and Registry Fixes Summary
|
|
|
|
## Overview
|
|
This document summarizes the fixes made to resolve installer issues and registry inconsistencies.
|
|
|
|
## Issues Fixed
|
|
|
|
### 1. Dead Registry References (13 Missing Files)
|
|
The following registry entries pointed to files that no longer existed on disk:
|
|
|
|
| Old Entry | Status | Resolution |
|
|
|-----------|--------|------------|
|
|
| `workflows-delegation` | Split | Replaced with 3 split files |
|
|
| `design-iteration` | Split | Replaced with 8 split files |
|
|
| `design-assets` | Missing | Removed from registry |
|
|
| `animation-patterns` | Split | Replaced with 6 split files |
|
|
| `adding-agent` | Split | Replaced with 2 split files |
|
|
| `adding-skill` | Split | Replaced with 3 split files |
|
|
| `navigation-design` | Split | Replaced with 2 split files |
|
|
| `external-libraries` | Split | Replaced with 3 split files |
|
|
| `claude-agent-skills` | Missing | Removed (directory doesn't exist) |
|
|
| `claude-create-subagents` | Missing | Removed (directory doesn't exist) |
|
|
| `claude-hooks` | Missing | Removed (directory doesn't exist) |
|
|
| `claude-plugins` | Missing | Removed (directory doesn't exist) |
|
|
| `navigation` (to-be-consumed) | Missing | Removed (directory doesn't exist) |
|
|
|
|
### 2. New Registry Entries Added (27 Files)
|
|
The following split files were added to the registry:
|
|
|
|
#### Task Delegation (3 files)
|
|
- `task-delegation-basics`
|
|
- `task-delegation-specialists`
|
|
- `task-delegation-caching`
|
|
|
|
#### Design Iteration (8 files)
|
|
- `design-iteration-overview`
|
|
- `design-iteration-plan-file`
|
|
- `design-iteration-plan-iterations`
|
|
- `design-iteration-stage-layout`
|
|
- `design-iteration-stage-theme`
|
|
- `design-iteration-stage-implementation`
|
|
- `design-iteration-stage-animation`
|
|
- `design-iteration-visual-content`
|
|
- `design-iteration-best-practices`
|
|
|
|
#### External Libraries (3 files)
|
|
- `external-libraries-workflow`
|
|
- `external-libraries-scenarios`
|
|
- `external-libraries-faq`
|
|
|
|
#### Adding Agent (2 files)
|
|
- `adding-agent-basics`
|
|
- `adding-agent-testing`
|
|
|
|
#### Adding Skill (3 files)
|
|
- `adding-skill-basics`
|
|
- `adding-skill-implementation`
|
|
- `adding-skill-example`
|
|
|
|
#### Navigation Design (2 files)
|
|
- `navigation-design-basics`
|
|
- `navigation-templates`
|
|
|
|
#### Animation (6 files)
|
|
- `animation-basics`
|
|
- `animation-advanced`
|
|
- `animation-components`
|
|
- `animation-forms`
|
|
- `animation-chat`
|
|
- `animation-loading`
|
|
|
|
### 3. Dependency Updates
|
|
Updated dependencies in the following components to reference new file IDs:
|
|
|
|
- **OpenCoder agent**: `workflows-delegation` → `task-delegation-basics`, `external-libraries` → `external-libraries-workflow`
|
|
- **OpenAgent agent**: `external-libraries` → `external-libraries-workflow`
|
|
- **External Context Integration context**: `workflows-delegation` → `task-delegation-basics`
|
|
- **Essential profile**: `workflows-delegation` → `task-delegation-basics`
|
|
|
|
### 4. Profile Fixes
|
|
Updated profile files to remove references to deleted components:
|
|
|
|
- **Essential**: Removed `to-be-consumed/*`, updated `adding-skill` → `adding-skill-basics`
|
|
- **Developer**: Removed `to-be-consumed/*`, `design-assets`, `animation-patterns`, added animation split files
|
|
- **Business**: Removed `to-be-consumed/*`
|
|
- **Full**: Removed `to-be-consumed/*`, updated `adding-skill` → `adding-skill-basics`
|
|
- **Advanced**: Removed `to-be-consumed/*`, updated `adding-skill` → `adding-skill-basics`
|
|
|
|
## Files Modified
|
|
|
|
### Registry & Configuration
|
|
- `registry.json` - Fixed dead references, added 27 new entries, updated dependencies
|
|
- `.opencode/config/agent-metadata.json` - Updated agent dependencies
|
|
|
|
### Profiles
|
|
- `.opencode/profiles/essential/profile.json` - Fixed references
|
|
- `.opencode/profiles/developer/profile.json` - Fixed references, added animation files
|
|
- `.opencode/profiles/business/profile.json` - Removed to-be-consumed
|
|
- `.opencode/profiles/full/profile.json` - Fixed references
|
|
- `.opencode/profiles/advanced/profile.json` - Fixed references
|
|
|
|
### New Scripts
|
|
- `scripts/registry/fix-registry.py` - Automated script to fix registry issues
|
|
- `scripts/tests/test-installer-files.sh` - Test script to verify installer file accessibility
|
|
|
|
## Testing
|
|
|
|
### Registry Validation
|
|
```bash
|
|
bun run scripts/registry/validate-registry.ts
|
|
```
|
|
**Result**: ✅ All 242 paths valid, 0 missing files, 0 missing dependencies
|
|
|
|
### Installer File Test (All Components)
|
|
```bash
|
|
./scripts/tests/test-installer-files.sh --local --all
|
|
```
|
|
**Result**: ✅ All 242 files accessible and would install successfully
|
|
|
|
### Installer File Test (Essential Profile)
|
|
```bash
|
|
./scripts/tests/test-installer-files.sh --local --profile=essential
|
|
```
|
|
**Result**: ✅ 22 files accessible, 0 failures
|
|
|
|
### Installer File Test (Developer Profile)
|
|
```bash
|
|
./scripts/tests/test-installer-files.sh --local --profile=developer
|
|
```
|
|
**Result**: ✅ 199 files accessible, 0 failures
|
|
|
|
## Impact Analysis
|
|
|
|
### Before Fixes
|
|
- **Missing files in registry**: 13
|
|
- **Orphaned files on disk**: 78
|
|
- **Missing dependencies**: 3
|
|
- **Installer would fail**: Yes, on 13 files
|
|
|
|
### After Fixes
|
|
- **Missing files in registry**: 0
|
|
- **Orphaned files on disk**: 66 (reduced by adding 27 split files)
|
|
- **Missing dependencies**: 0
|
|
- **Installer would fail**: No
|
|
|
|
## Remaining Orphaned Files
|
|
There are still 66 orphaned files (files that exist on disk but aren't in registry). These include:
|
|
- Navigation files (directory indexes)
|
|
- UI design guides (premium-dark-ui series)
|
|
- Lookup and example files
|
|
- Plugin documentation
|
|
|
|
These files are not essential for the installer and can be added to registry as needed.
|
|
|
|
## Usage
|
|
|
|
### Run Registry Validation
|
|
```bash
|
|
bun run scripts/registry/validate-registry.ts --verbose
|
|
```
|
|
|
|
### Test Installer Files (Remote Registry)
|
|
```bash
|
|
./scripts/tests/test-installer-files.sh --profile=essential
|
|
```
|
|
|
|
### Test Installer Files (Local Registry)
|
|
```bash
|
|
./scripts/tests/test-installer-files.sh --local --profile=essential
|
|
```
|
|
|
|
### Test All Components
|
|
```bash
|
|
./scripts/tests/test-installer-files.sh --local --all --verbose
|
|
```
|
|
|
|
## Notes
|
|
- The `to-be-consumed` directory no longer exists, so references to it have been removed
|
|
- Config files (`env.example`, `README.md`) exist at the repository root, not in `.opencode/`
|
|
- The installer test script can use either remote (GitHub) or local registry for testing
|
|
- All profile configurations have been updated to use valid component IDs
|