Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:
Troubleshooting in the Numan Registry project involves a multi-stage validation process designed to ensure the integrity, security, and compatibility of the signed official Numan registry index. The system employs several layers of checks, ranging from static secret scanning and schema validation to dynamic lifecycle testing against real Nushell binaries.
This guide focuses on diagnosing failures within the CI toolchain, including signature mismatches, artifact digest errors, and lifecycle proof failures. Maintainers should refer to Incident Response for operational procedures regarding compromise or rollbacks.
Sources: SECURITY.md:1-5, AGENTS.md:10-15
Validation Workflow Failures
The core of the troubleshooting process resides in the validation harness. Failures typically occur during one of the five stages of candidate validation or during the official index verification.
The diagram above illustrates the sequential dependency of validation scripts used in CI and local maintenance.
Sources: scripts/validate_candidate.py:15-22, REVIEW.md:7-15
Common Failure Points
| Failure Type | Script / Component | Root Cause |
|---|---|---|
| P0: Secret Leak | scan_for_secrets.py | Private key material (*.key, *.pem) committed to git. |
| P0: Trust Bypass | validate.py | Ed25519 signature does not match canonical JSON bytes. |
| P1: Digest Mismatch | validate.py | Downloaded artifact SHA-256 does not match index entry. |
| P1: Lifecycle Failure | lifecycle-prove.py | Package fails to install or activate in a clean Nu environment. |
| P2: Schema Drift | validate.py | index.json violates schemas/index-v1.json constraints. |
Sources: REVIEW.md:23-28, AGENTS.md:20-30
Signature and Integrity Issues
The registry relies on Ed25519 signatures over canonical JSON bytes. A signature failure indicates either a compromise of the index or a technical mismatch during the canonicalization process.
Placeholder Signatures
A frequent source of confusion is the PLACEHOLDER signature. In the source tree, registry/index.json.sig is intentionally a placeholder because production signing only occurs within the protected deployment workflow.
Sources: AGENTS.md:38-40, REVIEW.md:32-34
Verification Logic
Troubleshooting signature issues requires pointing validate.py to the correct public key and signature file.
python scripts/validate.py --index registry/index.json --sig <path_to_sig> --pub keys/official.pub
Sources: scripts/validate.py:12-14, AGENTS.md:23-25
Lifecycle Proof Failures (Stage 1)
The lifecycle-prove.py script is the final gate for activatable packages. It simulates a full user journey within a temporary Numan root.
This sequence ensures that a package can be managed throughout its entire lifecycle without polluting the host environment.
Sources: scripts/lifecycle-prove.py:108-121
Diagnosing "Package Not Found"
When running lifecycle-prove.py on new candidates, it may fail because it queries the production registry by default. New packages must be staged or the script must be pointed to a local candidate index for validation.
Sources: scripts/validate_candidate.py:145-150
Executable Resolution
Failures in the init or activate steps often stem from binary path issues. The script attempts to isolate the selected nu binary by creating a temporary shim or hardlink to prevent environmental contamination.
Sources: scripts/lifecycle-prove.py:187-200, scripts/lifecycle-prove.py:228-240
Intake and Candidate Errors
When validating new package specs via validate_candidate.py, the system performs structural lints and check for duplicate pull requests.
Duplicate Intake Warnings
The script warns if an open intake PR already exists for the same owner/name/version to prevent redundant work.
def _warn_open_intake_prs(owner: str, name: str, version: str) -> None:
branch = _intake_branch_name(owner, name, version)
existing = gh_json(["pr", "list", "--head", branch, "--state", "open"])
# ... logic to print warning ...
Sources: scripts/validate_candidate.py:34-45
Structural Linting
The lint_packages.py step (Stage 2) checks for:
- Missing mandatory fields.
- Unsupported archive suffixes (e.g., rejecting
.zipfor certain kinds). kind: sourceartifacts (only binary/archive artifacts are permitted for promotion).
Sources: scripts/validate_candidate.py:118-125, REVIEW.md:38-42
Summary
Troubleshooting the Numan Registry involves identifying which gate in the validation pipeline has failed. P0 issues regarding secrets and signatures must be addressed immediately by checking CI logs and git history. P1 and P2 issues involving artifact integrity or lifecycle proofing usually require re-running scripts/add-package.py to re-fetch digests or verifying the Nushell version constraints defined in the package spec.
Sources: REVIEW.md:23-30, scripts/validate_candidate.py:165-175