Command namespace specification (v0) :: Tools

Status: draft v0. The rule numbers match the concept page (NS-1..NS-14). Items marked PROVISIONAL are listed in Design decisions.

The key words MUST, MUST NOT, SHOULD and MAY are used as in RFC 2119.

Nodes and paths (NS-1)

The namespace is a tree. A node path is one or more words separated by /.
A word MUST match [a-z0-9][a-z0-9._+-]*. Paths are lowercase. A shell MAY fold case on input on case-insensitive platforms, but stored paths are lowercase.
Every node has a kind: verb (an action such as install; the resolver’s command is literally install, and on Unix install(1) lives at legacy/install, see Coexisting with install(1)), provider (one way to do a verb, such as install/npm), command (a plain runnable), alias (points at another path) or group (a container with no entry of its own).
Schema: schema/namespace-node.schema.json.

A tool claims nodes through a registration manifest (schema/registration-manifest.schema.json). Manifests are written in JSON5 (*.manifest.json5), format version 0. JSON5 parses to the JSON data model, so the JSON Schema validates the parsed value. Plain JSON is valid JSON5.
Every claim records its owning package id and version. A registry MUST be able to answer "who owns this path".
An alias MUST name a valid target path. The registry follows aliases while resolving and MUST detect loops.

Two claims on one path MUST NOT be resolved silently by "last installed wins".
If any claimant’s policy is refuse, the path is ambiguous: resolving it MUST fail and report every claimant.
If every claimant’s policy is shadow-with-warning, the first registered claim wins. The others are shadowed and MUST still appear in conflict reports.

Resolving an unknown name MUST NOT fail bare. Tools SHOULD offer did-you-mean candidates (edit distance on the last word and on the full path).
children(path) lists a node’s direct children, so every level of the tree can be browsed.

Entries found on the platform PATH are imported under legacy/<name> with policy shadow-with-warning, in PATH order. This keeps today’s PATH order while making the shadowing visible.
On Windows, within one folder, PATHEXT order picks which file <name> means. Names are case-folded.
A top-level name resolves to its namespace claim first, then to legacy/<name>.

Each runnable node declares entry.style: strict (the default, CLI Styles CS-1) or resolver.

A node MAY declare its subcommands, contextual flags (meaning depends on the verb) and free flags (meaning is the same everywhere). Free flags use the + sigil (decided), and repeating the sigil steps through levels.

A node MAY carry changed-since, keyed by an earlier version, listing tokens that were added, removed or changed. Tools use it to warn about scripts written for older versions.

An input signature (schema/input-signature.schema.json) declares which ambient context a command asks for: the current folder (none/read/write, always or only under a flag), environment variables, identity, network and stdin, plus its typed inputs and effects.
Signatures are declarations, not sandboxing. Isolation is the isolate front door’s job (NS-13, NS-14).

Levels overlay / fence / partition / guest x lifetimes run / session / kept x scope. Owned by isolate. Not part of this library.

The JSON5 manifests are the editable source of truth. A registry MAY compile them into an index for fast queries. The proposed index is SQLite; see Provisional decisions. The index can always be rebuilt from the manifests and MUST NOT be edited by hand.

source/command_namespace (D, dub package command-namespace):

Run dub test from the repository root.