valise-sh 0.2.0 → 0.3.0

package/lib/cli/usage.sh

@@ -0,0 +1,308 @@
+# Copyright (c) 2026 Joseph Cumines
+# SPDX-License-Identifier: MIT
+# valise CLI: per-command usage text.
+# Sourced by bin/valise; not executable on its own.
+
+usage() {
+  printf '%s\n' \
+    "Usage: valise <command> [options]" \
+    "" \
+    "Global option:" \
+    "  -C <dir>                  Run as if valise was started in dir" \
+    "" \
+    "Project commands (run anywhere inside a directory holding valise.conf):" \
+    "  new [dir]                 Scaffold a new valise project" \
+    "  module <new|list|remove>  Create, list, or remove project modules" \
+    "  build [--variant=<name>] [--bundle=<name>] [out]" \
+    "                            Build a release tree (default: build/release)" \
+    "  apply [--variant=<name>] [--bundle=<name>] [--no-integration] [--dry-run]" \
+    "                            Build the project, install it, and integrate it" \
+    "  status                    Show project, active release, integration, and drift" \
+    "  lint [--require-parsers] [module...]  Check metadata, layers, bundles, and syntax" \
+    "  test [--shell=<class>] [--require-shells] [module...]  Run module tests" \
+    "  run [--shell=<class>] [--module=<m>]... -- <script>  Run a script with modules loaded" \
+    "  env                       Print the engine, project, and storage paths" \
+    "" \
+    "Release commands:" \
+    "  install [--no-integration]  Install the release tree in the current directory" \
+    "  release <list|use|rollback|prune|verify>  Manage installed releases" \
+    "  uninstall [--keep-releases]  Remove the integration, commands, and releases" \
+    "  init [posix|fish]         Print the shell integration snippet" \
+    "  doctor [--pre-install] [--no-integration]  Run environment diagnostics" \
+    "" \
+    "Plumbing:" \
+    "  compile [--bundle=<name>] [--variant=<name>] <output-dir>  Compile plans only" \
+    "  registry [path]           Print the module table generated from metadata" \
+    "  make-manifest <tree> [--output <file>]  Write a release manifest for a tree" \
+    "  explain-variant [--bundle=<name>] [name]  Show a variant and its per-shell impact" \
+    "  explain-bundles [--bundle=<name>] [--variant=<name>]  Show each bundle's closure" \
+    "  layer-lint <name>         Validate a contribution layer structure" \
+    "  version                   Print version" \
+    "" \
+    "Environment:" \
+    "  XDG_DATA_HOME    Release storage root (default: ~/.local/share)" \
+    "  XDG_CONFIG_HOME  Active pointer symlink (default: ~/.config)" \
+    "  XDG_STATE_HOME   Lock and journal state (default: ~/.local/state)" \
+    "" \
+    "Run 'valise <command> --help' for command-specific usage."
+}
+
+# Per-command usage. Each command prints its own contract instead of the
+# global list, so `valise compile --help` names the arguments that command
+# actually accepts.
+
+usage_init() {
+  printf '%s\n' \
+    "usage: valise init [posix|fish] [--source-tree]" \
+    "" \
+    "Print the shell integration snippet for the active release. valise install" \
+    "and valise apply write it for you; use this to wire a startup file by hand." \
+    "" \
+    "  posix         A managed block for any POSIX shell. It loads the plan for" \
+    "                the running shell class: ksh, zsh, bash, or sh for any other." \
+    "  fish          The Fish conf.d hook." \
+    "  --source-tree Skip release verification in the Fish hook (development only)." \
+    "" \
+    "With no argument, fish when \$SHELL names fish, otherwise posix."
+}
+
+usage_install() {
+  printf '%s\n' \
+    "usage: valise install [--no-integration]" \
+    "" \
+    "Install the release tree in the current directory and make it active, then" \
+    "write the shell integration." \
+    "" \
+    "A managed block is written to ~/.profile; to the first of ~/.bash_profile and" \
+    "~/.bash_login that exists, because it shadows ~/.profile for bash; to ~/.bashrc" \
+    "and ~/.zshrc when that shell is \$SHELL or the file exists; and to ~/.zprofile" \
+    "when zsh is installed or the file exists. Symlinked files are left alone. A" \
+    "Fish conf.d hook is written when Fish is installed. Each install replaces the" \
+    "block in place. Each command the release publishes gets a stub in the command" \
+    "directory (see valise doctor)." \
+    "" \
+    "Every startup file is checked before the active release changes. If a later" \
+    "step fails, the previous active release is restored." \
+    "" \
+    "  --no-integration  Write no startup file, Fish hook, or command stubs."
+}
+
+usage_doctor() {
+  printf '%s\n' \
+    "usage: valise doctor [--pre-install] [--no-integration]" \
+    "" \
+    "Report the environment, the active release, and the shell integration." \
+    "" \
+    "  --pre-install     Skip the active-release and integration checks, for use" \
+    "                    before the first install." \
+    "  --no-integration  Check the environment and active release only."
+}
+
+usage_lint() {
+  printf '%s\n' \
+    "usage: valise lint [--require-parsers] [module...]" \
+    "" \
+    "Check the project: every metadata record and the files it names, each layer" \
+    "(contrib_ names, version=, dependencies inside the layer or the engine), the" \
+    "lint_layer_forbid pattern from valise.conf, every bundle compiled for every" \
+    "variant and shell, and the syntax of each body and test with the parser of" \
+    "every shell it declares. Listing modules limits the syntax checks to them." \
+    "" \
+    "  --require-parsers  Fail instead of skipping when a shell's parser is missing."
+}
+
+usage_test() {
+  printf '%s\n' \
+    "usage: valise test [--shell=<class>[,<class>...]] [--require-shells] [module...]" \
+    "" \
+    "Run the tests= scripts of each module (default: every module that has them)" \
+    "in every shell class it declares whose interpreter is installed: dash (or a" \
+    "plain sh) for sh, bash, zsh, ksh, and fish. Each run builds a release with" \
+    "the module as its only root, starts the shell with env -i, a fresh HOME," \
+    "TMPDIR and XDG directories, and PATH=\${VALISE_TEST_PATH:-/usr/bin:/bin:/usr/sbin:/sbin}" \
+    "plus the interpreter's directory, loads the module in strict mode, then runs" \
+    "the test. A test passes when it exits 0. Fish tests (*.fish) run only in" \
+    "Fish, other tests only in POSIX shells. A test can write fixtures and call" \
+    "valise_test_reload to load the module again. VALISE_TEST_ROOT, VALISE_TEST_MODULE," \
+    "VALISE_TEST_MODULE_DIR, VALISE_TEST_SHELL and VALISE_PROJECT_ROOT are set." \
+    "" \
+    "  --shell=<class>   Run only these shell classes." \
+    "  --require-shells  Fail instead of skipping when an interpreter is missing."
+}
+
+usage_run() {
+  printf '%s\n' \
+    "usage: valise run [--shell=<class>] [--module=<m>]... [--bundle=<b>] [--variant=<v>] [--keep-env] -- <script> [args...]" \
+    "" \
+    "Load modules into a shell and run a script there; the exit status is the" \
+    "script's. With --module the named modules are the only roots; otherwise the" \
+    "bundle and variant (default: valise.conf) select them. The shell class" \
+    "defaults to the one \$SHELL names, else sh. The environment is quarantined as" \
+    "for valise test unless --keep-env is given."
+}
+
+usage_env() {
+  printf '%s\n' \
+    "usage: valise env" \
+    "" \
+    "Print KEY=value lines, shell-quoted, for VALISE_VERSION, VALISE_ENGINE_ROOT," \
+    "VALISE_PROJECT_ROOT (empty outside a project), VALISE_DATA_DIR," \
+    "VALISE_CONFIG_DIR, VALISE_STATE_DIR, VALISE_RELEASES_DIR, VALISE_ACTIVE_LINK," \
+    "and VALISE_BIN_DIR."
+}
+
+usage_uninstall() {
+  printf '%s\n' \
+    "usage: valise uninstall [--keep-releases]" \
+    "" \
+    "Remove what valise install wrote: the managed block from each startup file" \
+    "(every other line is kept, and a file install created is deleted when it is" \
+    "left empty), the Fish hook, the command stubs valise owns, the active link," \
+    "and the installed releases. Files valise does not own are left alone." \
+    "" \
+    "  --keep-releases   Keep the installed releases." \
+    "" \
+    "The valise CLI itself is not removed."
+}
+
+usage_release() {
+  printf '%s\n' \
+    "usage: valise release <list|use|rollback|prune|verify> [options]" \
+    "" \
+    "  list                List installed releases and mark the active one." \
+    "  use <sha256>        Verify a release and make it active." \
+    "  rollback            Verify the release that was active before the last" \
+    "                      switch and make it active again." \
+    "  prune [--keep=N]    Remove older releases, keeping the active one and the" \
+    "                      N newest by modification time. A release that fails" \
+    "                      verification is kept, not removed." \
+    "  verify [--print-root]  Verify the sealed active release and optionally" \
+    "                      print its root." \
+    "" \
+    "prune --keep=0 keeps only the active release."
+}
+
+usage_new() {
+  printf '%s\n' \
+    "usage: valise new [dir]" \
+    "" \
+    "Scaffold a new valise project in dir (default: the current directory)." \
+    "" \
+    "The directory must be empty or absent. The scaffold contains valise.conf," \
+    "bundles.tsv with sh, bash, zsh, ksh and fish rows, variants.tsv, the POSIX" \
+    "seed module profile_main and the Fish seed module profile_main_fish."
+}
+
+usage_module() {
+  printf '%s\n' \
+    "usage: valise module <new|list|remove> [options]" \
+    "" \
+    "  new <name> [--exports=<list>] [--into=<module>[,...] | --no-wire]" \
+    "                                  Create a POSIX module in module.d/ and add it" \
+    "                                  to the requires= of the bundle's single POSIX" \
+    "                                  root, of the named modules, or of none." \
+    "  list                            List the project's and its layers' modules." \
+    "  remove <name>                   Remove a module and its references in metadata," \
+    "                                  bundle roots, and variant exclusions. Refuses" \
+    "                                  if that would leave a bundle or module empty."
+}
+
+usage_build() {
+  printf '%s\n' \
+    "usage: valise build [--variant=<name>] [--bundle=<name>] [out]" \
+    "" \
+    "Build a release tree from the project in the current directory." \
+    "" \
+    "  --variant=<name>  Build variant whose exclusion list applies (default:" \
+    "                    valise.conf variant=)." \
+    "  --bundle=<name>   Bundle whose roots seed each plan (default: valise.conf" \
+    "                    bundle=)." \
+    "  out               Output directory (default: build/release). An existing" \
+    "                    default output is replaced after a successful build." \
+    "                    An explicit output must be empty or absent." \
+    "" \
+    "The tree holds plans/<shell>.sh for each POSIX shell the bundle names," \
+    "runtime/capabilities.sh, valise-release.conf, manifest.tsv, and the metadata" \
+    "and bodies of exactly the modules some plan loads. Engine modules are copied" \
+    "under valise/, layer modules under layers/<provider>/. A module that" \
+    "publishes commands adds plans/commands/<module>.sh and bin/<command>; Fish" \
+    "roots add runtime/fish/."
+}
+
+usage_apply() {
+  printf '%s\n' \
+    "usage: valise apply [--variant=<name>] [--bundle=<name>] [--no-integration] [--dry-run]" \
+    "" \
+    "Build the project, install the result, write the shell integration, and verify" \
+    "the active release. See 'valise install --help' for the files it writes." \
+    "" \
+    "  --no-integration  Write no startup file, Fish hook, or command stubs." \
+    "  --dry-run         Build, then print what install would change: the release," \
+    "                    each startup file, the Fish hook, and the command stubs." \
+    "                    Nothing outside build/ is written."
+}
+
+usage_status() {
+  printf '%s\n' \
+    "usage: valise status" \
+    "" \
+    "Report the project defaults, the integration in each startup file, the bundle," \
+    "variant and valise version the active release was built with, and whether the" \
+    "active release matches build/release."
+}
+
+usage_compile() {
+  printf '%s\n' \
+    "usage: valise compile [--bundle=<name>] [--variant=<name>] <output-dir>" \
+    "" \
+    "Compile the project's modules into <output-dir>/<shell>.sh plans for the" \
+    "POSIX shells the bundle names. Use build for an installable release." \
+    "" \
+    "  --bundle=<name>   Bundle whose roots seed each plan (default: valise.conf)." \
+    "  --variant=<name>  Variant whose exclusion list applies (default: valise.conf)." \
+    "  output-dir        Destination directory. It must be empty or absent."
+}
+
+usage_registry() {
+  printf '%s\n' \
+    "usage: valise registry [path]" \
+    "" \
+    "Print the module table valise builds from metadata: the project's module.d/," \
+    "each layers/<provider>/module.d/, then the engine's own modules under the" \
+    "source valise. The table is internal; nothing needs to commit it." \
+    "" \
+    "  path  Write the table to this file instead of standard output."
+}
+
+usage_explain_bundles() {
+  printf '%s\n' \
+    "usage: valise explain-bundles [--bundle=<name>] [--variant=<name>]" \
+    "" \
+    "Show the roots and the ordered module closure each bundle resolves to, per" \
+    "shell, with each module's source." \
+    "" \
+    "  --bundle=<name>   Report one bundle instead of all of them." \
+    "  --variant=<name>  Apply this variant's exclusions (default: valise.conf)."
+}
+
+usage_layer_lint() {
+  printf '%s\n' \
+    "usage: valise layer-lint <layer-name>" \
+    "" \
+    "Validate a contribution layer's structure, namespace, metadata, load paths," \
+    "file modes, and dependency closure." \
+    "" \
+    "  layer-name  Provider directory under layers/, or a path to a layer" \
+    "              tree containing module.d/."
+}
+
+usage_explain_variant() {
+  printf '%s\n' \
+    "usage: valise explain-variant [--bundle=<name>] [variant-name]" \
+    "" \
+    "Show a variant's description, excluded modules, and how many of the bundle's" \
+    "roots it removes per shell." \
+    "" \
+    "  --bundle=<name>  Bundle to measure against (default: valise.conf)." \
+    "  variant-name     Variant from variants.tsv (default: valise.conf)."
+}

package/lib/compiler.awk

@@ -7,11 +7,13 @@
 #   Lines starting with MOD: identity<TAB>requires<TAB>load_path<TAB>platforms<TAB>side_effect<TAB>exports<TAB>optional
 #   identity is module@meta_source when registry sources are qualified.
 #   Lines starting with PRELUDE: sp_cap function names (space-separated)
-# Output: complete installed plan on stdout.
+# Output: complete installed plan on stdout. With -v mode=closure the
+# compiler validates and orders the closure, then prints one module identity
+# per line in load order instead of rendering a plan.
 
 BEGIN {
-    prefix = "_shell_installed_plan_"
-    prelude_dest = "vendor/shell-profile/lib/capabilities.sh"
+    prefix = "_valise_plan_"
+    prelude_dest = "runtime/capabilities.sh"
     seed_count = 0
     mod_count = 0
     prelude_fn_count = 0
@@ -306,8 +308,13 @@ END {
         }
     }
 
+    if (mode == "closure") {
+        for (oi = 1; oi <= ordered_count; oi++) print ordered[oi]
+        exit 0
+    }
+
     # --- Render plan ---
-    printf "# shell-profile-installed-modules-v1\n"
+    printf "# valise-plan-v2\n"
     printf "# Generated by valise compile; DO NOT EDIT.\n"
     printf "# plan=%s\n", plan_name
     printf "# roots="

package/lib/fish/loader.fish

@@ -157,6 +157,12 @@ function _sp_fish_loader_function_copy_matches --no-scope-shadowing --descriptio
     end
     set -l original_declaration (string replace -r '^function [^[:space:]]+' 'function __source_backed_copy__' -- "$original_lines[2]")
     set -l copy_declaration (string replace -r '^function [^[:space:]]+' 'function __source_backed_copy__' -- "$copy_lines[2]")
+    # `functions --copy` drops --wraps, which every `alias` sets. The option
+    # only links completions; the body and every other option must still
+    # agree. A restore re-checks full provenance and fails closed.
+    set -l wraps_option ' --wraps=(\'[^\']*\'|"[^"]*"|[^[:space:]]+)'
+    set original_declaration (string replace -r -a -- $wraps_option '' "$original_declaration")
+    set copy_declaration (string replace -r -a -- $wraps_option '' "$copy_declaration")
     test "$original_declaration" = "$copy_declaration"; or return 1
     set -l copy_index 3
     while test $copy_index -le (builtin count $copy_lines)
@@ -1582,6 +1588,21 @@ function _sp_fish_loader_load_ordered_impl --description 'Load modules from seed
             set -a reserved_function_before (builtin functions --details "$reserved_name")
         end
 
+        # Introspecting a name materializes Fish 3's autoloadable-but-undefined
+        # functions into `functions --all --names`, so the pre-loop snapshot is
+        # stale by the time the body runs. Re-capture the diff baseline after the
+        # snapshot loop and before sourcing; otherwise Fish's own system functions
+        # would be attributed to the body and published in the ownership ledger
+        # with an unauthenticatable `/usr/share/fish` source. The snapshot copies
+        # above are already defined, but are re-added defensively so a baseline
+        # that failed to enumerate them can never classify them as body output.
+        set -l function_names_before (builtin functions --all --names)
+        for caller_function_snapshot in $caller_function_snapshot_copies
+            if not builtin contains -- "$caller_function_snapshot" $function_names_before
+                set -a function_names_before "$caller_function_snapshot"
+            end
+        end
+
         # Snapshot private loader globals before sourcing. Module bodies are
         # allowed to publish their declared functions, not to rewrite the
         # loader's discovery roots, provider cache, or loaded set.
@@ -1975,14 +1996,22 @@ function _sp_fish_loader_load_ordered_impl --description 'Load modules from seed
             builtin set loader_state_changed 1
         end
         # Classify all protected-state and function mutations before rollback.
-        # A combined handshake mutation plus embedded `cd` mutation must never
-        # enter a return path that leaves the embedded function installed.
+        # A combined handshake mutation plus `cd` mutation must never enter a
+        # return path that leaves a replacement critical function installed.
+        # Fish 4 embeds `cd`; Fish 3 loads it from the installation function
+        # path. Both are Fish-provided definitions the loader cannot restore
+        # with provenance after a body replaces them, so both fail closed.
         set -l preflight_embedded_mutation ''
         set -l preflight_embedded_index 1
         for preflight_reserved_name in $reserved_function_names
             set -l preflight_before_source "$reserved_function_before[$preflight_embedded_index]"
             set -l preflight_after_source (builtin functions --details "$preflight_reserved_name")
-            if builtin string match -q 'embedded:*' -- "$preflight_before_source"; and not builtin test "$preflight_after_source" = "$preflight_before_source"
+            set -l preflight_before_dir (builtin path dirname -- "$preflight_before_source")
+            set -l preflight_fish_provided 0
+            if builtin string match -q 'embedded:*' -- "$preflight_before_source"; or builtin test "$preflight_before_source" = builtin; or builtin contains -- "$preflight_before_dir" /usr/share/fish/functions /usr/local/share/fish/functions /opt/local/share/fish/functions /opt/homebrew/share/fish/functions
+                set preflight_fish_provided 1
+            end
+            if builtin test $preflight_fish_provided -eq 1; and not builtin test "$preflight_after_source" = "$preflight_before_source"
                 set preflight_embedded_mutation "$preflight_reserved_name"
                 break
             end
@@ -2175,8 +2204,24 @@ function _sp_fish_loader_load_ordered_impl --description 'Load modules from seed
         set -g _sp_fish_loaded_modules $_sp_fish_loaded_modules $mod
         for owned_function in $new_function_names $mod_exports
             if test -n "$owned_function"; and not builtin contains -- $owned_function $_sp_fish_loader_owned_exports
+                set -l owned_source (builtin functions --details "$owned_function")
+                # Fish's own system functions are not module state. A body can
+                # materialize them by sourcing a completion or function file or
+                # by running completions, but the ledger must not claim them:
+                # their source is not an authenticated release path, so the next
+                # activation would fail closed, and its cleanup would erase real
+                # Fish functions. Fish 3 reports a file under the installation
+                # prefix; Fish 4 reports an embedded: path. A module's own
+                # functions report their body file (or "-" for an alias), so they
+                # are unaffected. Rollback still removes these from
+                # new_function_names because, for a failed body, they are this
+                # activation's residue.
+                switch "$owned_source"
+                    case '/usr/share/fish/*' '/usr/local/share/fish/*' '/opt/local/share/fish/*' '/opt/homebrew/share/fish/*' 'embedded:completions/*' 'embedded:functions/*' 'autoloaded:*'
+                        continue
+                end
                 set -a _sp_fish_loader_owned_exports $owned_function
-                set -a _sp_fish_loader_owned_sources (builtin functions --details "$owned_function")
+                set -a _sp_fish_loader_owned_sources $owned_source
             end
         end
     end
@@ -2235,13 +2280,28 @@ function _sp_fish_loader_init --description 'Initialize the Fish loader with sta
     # providers, followed by engine generic metadata and project generic
     # metadata. Duplicate names are accepted only when metadata and native
     # Fish bodies are byte-identical; conflicting providers fail closed.
+    # A built release (valise-release.conf beside runtime/) ships its loader at
+    # runtime/fish/loader.fish, so ../.. is the release root. Its providers are
+    # the primary modules, each layers/<provider>, then the engine modules
+    # under valise/, in the order valise build resolves them.
+    if test -n "$engine_root"; and test -f "$engine_root/valise-release.conf"
+        if test -d "$engine_root/module.d"
+            sp_fish_loader_add_root "$engine_root"; or return 1
+        end
+        for layer_root in "$engine_root"/layers/*
+            if test -d "$layer_root/module.d"
+                sp_fish_loader_add_root "$layer_root"; or return 1
+            end
+        end
+        if test -d "$engine_root/valise/module.d"
+            sp_fish_loader_add_root "$engine_root/valise"; or return 1
+        end
+        return 0
+    end
+
     set -l project_root ''
     if set -q SHELL_PROJECT_ROOT
-        if test -d "$SHELL_PROJECT_ROOT/shell/module.d"; and test -d "$SHELL_PROJECT_ROOT/shell/modules"
-            set project_root "$SHELL_PROJECT_ROOT/shell"
-        else
-            set project_root "$SHELL_PROJECT_ROOT"
-        end
+        set project_root "$SHELL_PROJECT_ROOT"
     end
     if test -n "$project_root"; and test -d "$project_root/modules/fish"
         sp_fish_loader_add_root "$project_root/modules/fish"; or return 1

package/lib/fish/metadata.fish

@@ -76,7 +76,7 @@ function sp_fish_metadata_validate_shell_list --description 'Validate shell list
         end
         set seen 1
         switch "$sh"
-            case sh bash zsh ksh fish
+            case posix sh bash zsh ksh fish
                 # valid
             case '*'
                 sp_fish_metadata_error "invalid shell: $sh"
@@ -190,7 +190,10 @@ function sp_fish_metadata_read --description 'Read and validate a .meta file, ou
     set -l m_platforms ''
     set -l m_side_effect ''
     set -l m_exports ''
-    set -l m_updates ''
+    set -l m_commands ''
+    set -l m_executables ''
+    set -l m_tests ''
+    set -l m_seen
     set -l m_version ''
     set -l m_load ''
 
@@ -206,6 +209,11 @@ function sp_fish_metadata_read --description 'Read and validate a .meta file, ou
         end
         set -l key (string split -m1 '=' -- "$line")[1]
         set -l val (string split -m1 '=' -- "$line")[2]
+        if contains -- "$key" $m_seen
+            sp_fish_metadata_error "duplicate metadata field: $key"
+            return 1
+        end
+        set -a m_seen "$key"
         switch "$key"
             case name; set m_name $val
             case requires; set m_requires $val
@@ -214,7 +222,12 @@ function sp_fish_metadata_read --description 'Read and validate a .meta file, ou
             case platforms; set m_platforms $val
             case side_effect; set m_side_effect $val
             case exports; set m_exports $val
-            case updates; set m_updates $val
+            case commands; set m_commands $val
+            case executables; set m_executables $val
+            case tests; set m_tests $val
+            case updates
+                sp_fish_metadata_error 'metadata field updates is not supported since valise 0.3.0; publish commands with commands= or executables='
+                return 1
             case version; set m_version $val
             case load; set m_load $val
             case load_hook
@@ -275,9 +288,38 @@ function sp_fish_metadata_read --description 'Read and validate a .meta file, ou
     if not sp_fish_metadata_validate_identifier_list "$m_exports" export
         return 1
     end
-    if not sp_fish_metadata_validate_identifier_list "$m_updates" update_registration
+    if not sp_fish_metadata_validate_identifier_list "$m_commands" command
         return 1
     end
+    for cmd in (string split ' ' -- $m_commands)
+        test -n "$cmd"; or continue
+        if not contains -- "$cmd" (string split ' ' -- $m_exports)
+            sp_fish_metadata_error "command is not a declared export: $cmd"
+            return 1
+        end
+    end
+    for kind in executable test
+        set -l paths $m_executables
+        test "$kind" = test; and set paths $m_tests
+        if string match -qr '[*?\[\]\\\\]' -- "$paths"
+            sp_fish_metadata_error "invalid $kind: contains glob metacharacter"
+            return 1
+        end
+        for p in (string split ' ' -- $paths)
+            test -n "$p"; or continue
+            if string match -qr '(^|/)\.(/|$)|//|/$' -- "$p"
+                sp_fish_metadata_error "invalid $kind path: $p"
+                return 1
+            end
+            if not sp_fish_metadata_validate_relative_path "$p"
+                return 1
+            end
+            if test "$kind" = executable; and not string match -qr '^[A-Za-z0-9_]' -- (string split -r -m1 / -- "$p")[-1]
+                sp_fish_metadata_error "invalid executable name: "(string split -r -m1 / -- "$p")[-1]
+                return 1
+            end
+        end
+    end
     if not sp_fish_metadata_validate_version "$m_version"
         return 1
     end
@@ -292,7 +334,9 @@ function sp_fish_metadata_read --description 'Read and validate a .meta file, ou
     echo "platforms=$m_platforms"
     echo "side_effect=$m_side_effect"
     echo "exports=$m_exports"
-    echo "updates=$m_updates"
+    echo "commands=$m_commands"
+    echo "executables=$m_executables"
+    echo "tests=$m_tests"
     echo "version=$m_version"
     echo "load=$m_load"
     return 0