Package Specifications

Relevant source files

The following files were used as context for generating this wiki page:

• scripts/add-package.py
• scripts/gen_candidate.py
• scripts/validate_candidate.py
• registry/index.json
• README.md
• specs/cptpiepmatz-nu_plugin_highlight-1.4.16.json

Package Specifications serve as the foundational configuration files used to define metadata, artifact locations, and compatibility requirements for Nushell packages within the Numan registry. These specifications are small JSON files that provide the necessary data for the add-package.py utility to download artifacts, compute SHA-256 digests, and merge new entries into the official registry index.

The specification lifecycle moves through several stages: discovery, candidate generation, validation, and finally, integration into the signed index.json. This process ensures that no maintainer manually types sensitive data like checksums, reducing the risk of broken or malicious package distributions.

Sources: README.md:38-51, scripts/add-package.py:1-20, scripts/gen_candidate.py:1-12

Specification Structure

A package specification must include top-level fields identifying the owner, name, and type of the package. It defines the artifact's nature (e.g., binary or archive) and the Nushell versions it is compatible with.

Core Metadata Fields

The following fields are mandatory for all valid specifications:

Field	Type	Description
owner	String	The GitHub username or organization owning the repository.
name	String	The name of the package.
description	String	A brief overview of the package's functionality.
repo	String	The URL to the source code repository.
type	String	Must be one of: plugin, module, script, or completion.
tags	Array	A list of strings used for catalog filtering.
version	String	The package's semantic version.
nu_version	String	Semantic version constraint for Nushell (e.g., >=0.114.0).
artifact	Object	Defines the download parameters and artifact kind.

Sources: scripts/add-package.py:126-140, scripts/gen_candidate.py:130-143

Artifact Types

The system supports two primary artifact kinds: binary (typically for plugins) and archive (for modules and scripts).

1. Binary Artifacts: Require a targets mapping that links specific platform triples (e.g., x86_64-pc-windows-msvc) to a download URL and an executable_path within the archive.
2. Archive Artifacts: Require a single url and an entry point (e.g., mod.nu).

Sources: scripts/add-package.py:28-66, scripts/gen_candidate.py:102-127

Data Flow and Lifecycle

The lifecycle of a package specification involves multiple scripts that transform raw repository data into a validated registry entry.

Sources: scripts/gen_candidate.py:1-15, scripts/validate_candidate.py:1-25

Validation and Automated Hashing

The add-package.py script is critical for technical accuracy. It downloads each artifact defined in the spec to compute a SHA-256 hash automatically. This prevents manual entry of digests, which is a prohibited practice in the registry architecture.

def download_and_hash(url):
    # Ensures URL is HTTP/HTTPS and computes SHA256
    print(f"  downloading {url} ...", file=sys.stderr)
    with http_opener().open(req, timeout=60) as resp:
        data = resp.read()
    digest = hashlib.sha256(data).hexdigest()
    return digest

Sources: scripts/add-package.py:100-117, REVIEW.md:38-40

Implementation Example

Specifications provide the blueprint for entries in the index.json. Below is an example of a specification for a syntax highlighting plugin that includes source provenance.

{
  "owner": "cptpiepmatz",
  "name": "nu_plugin_highlight",
  "type": "plugin",
  "version": "1.4.16",
  "nu_version": ">=0.114.0 <0.115.0",
  "verified_with": ["0.114.1"],
  "source": {
    "git": "https://github.com/cptpiepmatz/nu-plugin-highlight%22%2C
    "rev": "c0e768d66e9cff17c791e1c5138d518409285599",
    "cargo_name": "nu_plugin_highlight"
  },
  "artifact": {
    "kind": "binary",
    "targets": {
      "x86_64-pc-windows-msvc": {
        "url": "https://github.com/.../nu_plugin_highlight.zip%22%2C
        "executable_path": "nu_plugin_highlight.exe"
      }
    }
  }
}

Sources: specs/cptpiepmatz-nu_plugin_highlight-1.4.16.json:1-38, scripts/add-package.py:192-212

Activation and Compatibility

For module types, specifications can include an activation block. Numan follows a strict convention for module entry points. If the entry file is mod.nu, the activation import must be set to all to ensure commands are imported correctly without improper prefixing.

Activation Field	Description	Requirement
kind	Type of activation.	Typically nu-module.
import	How the module is imported.	all for mod.nu; module for others.

Sources: scripts/add-package.py:83-97, registry/index.json:62-65

Summary

Package Specifications are the primary vehicle for registry expansion. By automating the hashing of artifacts and enforcing strict schema validation through scripts like validate_candidate.py, the Numan registry maintains a high standard of trust and technical integrity. Specifications ensure that every package version is tied to specific Nushell versions and carries immutable provenance data before being signed and published to the production CDN.