cclohmar/OpenWriterControle
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
OpenWriterControle/docs/maintenance/REGISTRY_FIXES_SUMMARY.md
Darren Hinde 013682c499
fix: resolve installer failures and add comprehensive validation (#189) 
* 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
2026-02-06 17:07:42 +00:00

6.2 KiB
Raw Blame History

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

bun run scripts/registry/validate-registry.ts

Result: ✅ All 242 paths valid, 0 missing files, 0 missing dependencies

Installer File Test (All Components)

./scripts/tests/test-installer-files.sh --local --all

Result: ✅ All 242 files accessible and would install successfully

Installer File Test (Essential Profile)

./scripts/tests/test-installer-files.sh --local --profile=essential

Result: ✅ 22 files accessible, 0 failures

Installer File Test (Developer Profile)

./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

bun run scripts/registry/validate-registry.ts --verbose

Test Installer Files (Remote Registry)

./scripts/tests/test-installer-files.sh --profile=essential

Test Installer Files (Local Registry)

./scripts/tests/test-installer-files.sh --local --profile=essential

Test All Components

./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