valise-sh 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -3,7 +3,157 @@
 Notable user-facing changes are recorded here. Versions before 1.0 may include
 module ABI or CLI changes; see [the release policy](docs/release-policy.md).
 
-## [Unreleased]
+## [0.3.0] - 2026-11-06
+
+0.3.0 changes the project layout, the metadata, and the release format. A
+0.2 project must be moved to the new layout and its releases rebuilt; see
+[What changed in 0.3.0](docs/release-policy.md#what-changed-in-030).
+
+### Added
+
+- Published commands. Metadata `commands=` names exports to publish and
+  `executables=` names scripts. `valise build` writes a command plan per
+  module under `plans/commands/` and a launcher per name under `bin/`, and
+  install writes a stub for each into
+  `${VALISE_BIN_DIR:-${XDG_BIN_HOME:-$HOME/.local/bin}}`. valise records
+  the stubs it writes in `$XDG_STATE_HOME/valise/commands.tsv` and never
+  replaces or removes a file it did not write. `valise doctor` reports
+  collisions and a command directory missing from `PATH`.
+- `valise lint [--require-parsers] [module...]` checks metadata, layers,
+  every bundle compiled for every variant and shell, and the syntax of each
+  body and test with the parser of every shell the module declares. The
+  `valise.conf` key `lint_layer_forbid` makes lint reject a pattern, such as
+  an employer name, anywhere under `layers/`.
+- `valise test [--shell=<class>] [--require-shells] [module...]` runs each
+  module's `tests=` scripts in every declared shell that is installed, in
+  an `env -i` environment with a fresh `HOME` and XDG tree.
+  `valise_test_reload` lets a test write fixtures and load the module again.
+- `valise run [--shell=<class>] [--module=<m>]... [--bundle=<b>]
+  [--variant=<v>] [--keep-env] -- <script>` loads modules into a shell and
+  runs a script there.
+- `valise env` prints the engine, project, and storage paths as shell-quoted
+  `KEY=value` lines.
+- `valise test` and `valise run` export `VALISE_TEST_RELEASE` and
+  `VALISE_TEST_PLAN`, so a test can load the same modules in a child shell.
+- `valise uninstall [--keep-releases]` removes the managed blocks (keeping
+  every other byte and the file mode), the startup files install created
+  that are left empty, the Fish hook, the owned command stubs, the active
+  link, and the installed releases.
+- `valise release rollback` makes the previously active release active
+  again. Every switch records the release it replaced in
+  `$XDG_STATE_HOME/valise/previous`.
+- `valise apply --dry-run` builds the project and prints what install would
+  change in the release store, the startup files, the Fish hook, and the
+  command directory, without writing outside `build/`.
+- A bundle's `fish` rows build the native Fish runtime into the release
+  under `runtime/fish/`, and the Fish hook loads the bundle's Fish roots
+  from it. `valise new` scaffolds a Fish seed module.
+- `valise -C <dir>` runs a command as if started in `dir`. Project commands
+  find the project from any subdirectory.
+- `valise.conf` key `requires_valise`: an older valise refuses to build the
+  project.
+- `valise module new --into=<module>[,...]` and `--no-wire` for projects
+  whose default bundle has several POSIX roots.
+- Metadata `tests=` names the test scripts of a module.
+- `shells=posix` names every POSIX shell.
+- `docs/projects.md` describes the project layout, bundles, variants,
+  compile, and build.
+
+### Changed
+
+- A project is the directory holding `valise.conf`, with `module.d/`,
+  `modules/`, `layers/<provider>/`, `bundles.tsv`, and `variants.tsv` at its
+  root. `valise.conf` replaces `shell/release/project.conf`, `bundles.tsv`
+  replaces `shell/release/bundle-roots`, and `variants.tsv` replaces
+  `shell/release/install-variants`. The `shell/` layout is not read.
+- The registry is internal: `valise build` generates it on demand from the
+  metadata, and `valise registry` prints it. It has columns for `commands`,
+  `executables`, and `tests` and a `source` of `module.d`,
+  `layers/<provider>/module.d`, or `valise`.
+- The engine modules are renamed into the reserved `valise_` namespace
+  (`valise_path`, `valise_editor`, `valise_history`, `valise_pager`,
+  `valise_xdg`, `valise_platform_posix`, `valise_platform_macos`,
+  `valise_platform_linux`, `valise_platform_bsd`), with exports renamed to
+  match, such as `valise_path_prepend`. They are available to every
+  project without vendoring. A project or layer module may not use the
+  `valise_` prefix, and layer modules must use `contrib_`.
+- `shells=sh` names only the generic POSIX class (dash, BusyBox ash, and
+  other plain `sh`), so `shells=sh bash ksh` loads in dash, bash, and ksh
+  and not in zsh. Use `shells=posix` for every POSIX shell.
+- Release format 2. A release holds `plans/<shell>.sh` for `sh`, `bash`,
+  `zsh`, and `ksh`, `runtime/capabilities.sh`, `valise-release.conf`
+  (`format=2`, the bundle, the variant, the roots per shell, the modules,
+  and the commands), and `manifest.tsv`. It contains only the modules some
+  plan loads, so a module a variant excludes is absent with its body.
+  Install refuses a tree without `format=2`.
+- The POSIX managed block picks the plan for `ksh`, `zsh`, `bash`, or `sh`
+  and sets its guard only after the plan loaded, so a later startup file
+  retries after a failure.
+- Install is transactional. It checks every startup file, the Fish hook
+  path, and (when commands are published or already tracked) the command
+  directory before changing the active release and, if a later step fails,
+  restores the previous active release, the previous-release record, and
+  the command stubs, and names the files it already wrote. A new managed
+  block is appended with nothing around it, so uninstall restores the file
+  exactly. Text after a block keeps the file's ending, with or without a
+  final newline, and a repeat install rewrites nothing.
+- Install warns, and `valise doctor` fails, on a line outside a managed block
+  that loads valise by hand.
+- `valise build` moves the previous `build/release` aside and restores it if
+  publication fails.
+- An identical installed Fish hook is left in place, and apply reports
+  `Fish hook current`.
+- `valise status` reports the bundle, variant, and valise version the active
+  release was built with, separately from the project defaults.
+- `valise explain-variant` counts the roots and modules a variant keeps per
+  shell, resolving qualified names.
+- `bin/valise` is a dispatcher over the parts in `lib/cli/`.
+- The package `files` list names every shipped file, so packing a local tree
+  ships only the runtime, the docs, and the example sources, not stray local
+  files. A test fails when a tracked file is missing from the list.
+
+### Removed
+
+- The `shell/` project layout, `registry --check`, and the committed
+  registry.
+- Metadata `updates=`. Metadata naming it fails with a message naming
+  0.3.0.
+- The engine release shape: `entrypoints/fish/profile.fish`, the POSIX
+  block's loader fallback, and the Fish hook's `generated/`, `vendor/`, and
+  entrypoint routes.
+- `examples/e2e/build-manifest.sh`; `examples/e2e` is a valise project built
+  with `valise build`.
+- `docs/variants.md`, replaced by `docs/projects.md`.
+
+### Fixed
+
+- `sp_cap_secure_local_bin_check` accepts `allow-owned-symlinks`. The default
+  still rejects every symlink in `~/.local/bin`; the option accepts a symlink
+  whose link entry is owned by the current user, which is how pipx and uv
+  publish commands, while still rejecting unowned entries and group- or
+  other-writable regular files.
+- A repeated metadata field was silently overwritten by the last value; the
+  POSIX and Fish readers now reject it.
+- The Fish loader rejected caller aliases, because `functions --copy` drops
+  `--wraps`.
+- Fish 3 lists autoloadable but undefined functions in `functions --all
+  --names`, and that list grows as the loader introspects it. The Fish loader
+  and the generated hook now take their "created by this activation" baseline
+  after that introspection, so Fish's own system functions are no longer
+  attributed to a module or an entrypoint and published in an ownership
+  ledger whose `/usr/share/fish` source can never be authenticated.
+- A body that replaced `cd` on Fish 3, where `cd` is a file-backed system
+  function rather than an embedded one, was reported as a generic loader-state
+  mutation. It now fails closed as a mutated critical Fish function, matching
+  Fish 4.
+- A module body that sourced a Fish completion or function file, or ran
+  completions, materialized Fish's own system functions. Those entered the
+  ownership ledger, so the next activation failed closed before its cleanup
+  erased real Fish functions. Fish system functions are no longer recorded as
+  module- or entrypoint-owned, on Fish 3 (file paths) and Fish 4 (embedded
+  paths) alike.
+- `valise doctor` did not accept FreeBSD's `sha256`.
+- `valise module new` assumed the seed module was `profile_main`.
 
 ## [0.2.0] - 2026-10-31
 
@@ -172,6 +322,6 @@ module ABI or CLI changes; see [the release policy](docs/release-policy.md).
 - The editor-defaults test is independent of host-installed editors by
   supplying a temporary test `vi` executable.
 
-[Unreleased]: https://github.com/joeycumines/valise-sh/compare/v0.2.0...HEAD
+[0.3.0]: https://github.com/joeycumines/valise-sh/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/joeycumines/valise-sh/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/joeycumines/valise-sh/releases/tag/v0.1.0

package/README.md

@@ -1,170 +1,123 @@
 # valise-sh
 
-valise-sh is a POSIX shell-profile engine. It loads shell configuration from
-modules described by declarative metadata files. The metadata is parsed as
-data and never executed; the loader resolves the dependency graph and sources
-module bodies in deterministic order. The POSIX core runs under `sh`, `dash`,
-`ksh`, and `bash`; Fish is supported through a native loader in `lib/fish/`.
-The repository also includes the `valise` CLI, which installs sealed
-shell-profile releases and verifies them before use.
-
-A consuming project can split its shell configuration into modules with
-declared dependencies, then test and select those modules explicitly. The
-engine is designed to be vendored by that project, for example as a Git
-submodule; the consumer owns its profile and release contents.
-
-## Try a sample release
-
-This walkthrough builds and installs the included sample profile in an
-isolated temporary home. `valise install` deploys its normal shell
-integration there, so your real home directory and startup files are left
-untouched.
+valise builds your shell profile from modules. Each module is a metadata file
+and a shell body; valise reads the metadata as data, compiles a static
+startup plan for each shell, and installs the result as a sealed, verified
+release. sh, dash, BusyBox ash, bash, zsh, and ksh load the compiled POSIX
+plans; Fish has a native loader.
+
+You keep your modules in a valise project. The engine supplies the `valise`
+CLI and a few generic modules (`valise_path`, `valise_editor`, and others).
+
+## Quick start
 
 ```sh
 git clone https://github.com/joeycumines/valise-sh.git
-cd valise-sh
-export PATH="$PWD/bin:$PATH"
+export PATH="$PWD/valise-sh/bin:$PATH"
 
-# Isolate HOME and XDG state; the trap also removes read-only release files.
-(
-  set -eu
-  _demo_state=$(mktemp -d)
-  cleanup_demo() {
-    chmod -R u+w "$_demo_state" 2>/dev/null || :
-    rm -rf "$_demo_state"
-  }
-  trap cleanup_demo EXIT
-  trap 'exit 130' INT
-  trap 'exit 143' TERM
-  mkdir -p "$_demo_state/home"
-  export HOME="$_demo_state/home"
-  export XDG_DATA_HOME="$_demo_state/data"
-  export XDG_CONFIG_HOME="$_demo_state/config"
-  export XDG_STATE_HOME="$_demo_state/state"
-
-  # Build, install, and apply the sample profile project.
-  (cd examples/profile-project && valise apply)
-
-  # Run the greeting function exposed by the active profile.
-  bash -l -c 'greet'
-)
+valise new my-profile
+cd my-profile
+valise module new hello --exports=hello
+$EDITOR modules/hello.sh
+valise lint
+valise apply
 ```
 
-For the multi-shell test fixture and verification scenarios, see
-[examples/e2e/README.md](examples/e2e/README.md). For the smallest possible
-loader example without installation, use `examples/local/` as described in
-[examples/README.md](examples/README.md).
-
-## Build your own profile
+`valise apply` builds the project, installs the release, writes a managed
+block into your startup files, and verifies the active release. Open a new
+login shell to load it. `valise apply --dry-run` shows what would change
+first, and `valise uninstall` removes everything install wrote.
 
-The sample above loads modules from an example profile. To build your own,
-start from the project scaffold:
+To try it without touching your real home directory, point `HOME` and the
+XDG directories at a scratch directory:
 
 ```sh
-export PATH="$PWD/bin:$PATH"
-valise new my-profile
-cd my-profile
+(
+  set -eu
+  demo=$(mktemp -d)
+  trap 'chmod -R u+w "$demo"; rm -rf "$demo"' EXIT
+  export HOME="$demo/home" XDG_DATA_HOME="$demo/data" \
+    XDG_CONFIG_HOME="$demo/config" XDG_STATE_HOME="$demo/state" \
+    XDG_BIN_HOME="$demo/bin"
+  mkdir -p "$HOME"
+  cd valise-sh/examples/profile-project
+  valise apply
+  bash -l -c greet
+)
 ```
 
-That writes a project with a metadata directory, a module body, bundle
-roots, variants, and `project.conf`. Add modules with `valise module new`,
-then build and install:
+## A project
 
-```sh
-valise build   # build a release under build/release/
-valise apply   # install it and write the managed shell integration
+```
+valise.conf      project settings
+module.d/        <name>.meta: one metadata file per module
+modules/         module bodies
+layers/<p>/      modules vendored from another provider (optional)
+bundles.tsv      the root modules for each shell
+variants.tsv     named sets of modules to leave out (optional)
+```
+
+A module's metadata names its dependencies, the shells and platforms it
+supports, the functions it exports, and optionally the exports to publish
+as commands on `PATH`:
+
+```text
+name=hello
+version=1.0.0
+side_effect=read-only
+requires=valise_path
+optional=
+shells=posix
+platforms=any
+exports=hello
+commands=hello
+tests=tests/hello.sh
+load=modules/hello.sh
 ```
 
-`examples/profile-project/` is a worked version of this: it has two modules,
-a provider layer, two variants, and a bundle. Its
-[README](examples/profile-project/README.md) walks through each step and
-explains what the generated release contains.
-
-## Repository layout
-
-- `entrypoints/profile.sh` — the portable entrypoint. It is sourced, not
-  executed: it resolves the engine root, sources the three libraries, and
-  calls the loader with the requested modules.
-- `lib/metadata.sh` — parses `module.d/*.meta` files as data and validates
-  identifiers, lists, paths, shells, platforms, and side-effect classes.
-- `lib/loader.sh` — resolves the dependency closure, selects modules by
-  shell/platform/phase, sources bodies, checks declared exports, and cleans
-  up on failure.
-- `lib/capabilities.sh` — portable helpers (`sp_cap_*`) that modules call
-  instead of platform-specific commands.
-- `lib/fish/` — native Fish loader and metadata reader. The Fish path never
-  sources POSIX shell bodies.
-- `bin/valise` — the CLI: init, install, release, doctor, make-manifest,
-  registry, new, module, build, apply, status, compile, explain-variant,
-  explain-bundles, layer-lint, version.
-  `init`, `install`, `release`, `doctor`, `make-manifest`, `new`, and
-  `version` run from a bare checkout. `registry`, `module`, `build`, `apply`,
-  `status`, `compile`, `explain-variant`,
-  `explain-bundles`, and `layer-lint` require the consuming project's source
-  tree (see [docs/variants.md](docs/variants.md) and
-  [docs/contrib-modules.md](docs/contrib-modules.md)). No command requires
-  Python 3.
-- `module.d/` and `modules/platform/` — generic platform modules
-  (`platform_posix`, `platform_macos`, `platform_linux`, `platform_bsd`).
-- `manifests/parser-support.tsv` — declares the shell parsers used to check
-  each source-file class.
-- `tests/` — the test suite. Every test runs in a quarantined environment:
-  fresh temporary HOME, controlled TMPDIR and PATH, cleared startup hooks.
-- `examples/local/` — a minimal runnable module demonstrating the metadata
-  contract.
-- `examples/profile-project/` — a complete consuming project: metadata,
-  bodies, a provider layer, bundles, variants, and project defaults. Its
-  [README](examples/profile-project/README.md) walks from clone to a loaded
-  profile.
-
-Product-specific modules, adapters, release packaging, and installer
-transactions belong in the consuming project, not here. See
-[docs/architecture.md](docs/architecture.md) for the scope.
+## Commands
 
-## Documentation
+| Command | Does |
+|---|---|
+| `new`, `module new\|list\|remove` | Scaffold a project and its modules. |
+| `lint`, `test`, `run`, `env` | Check metadata and syntax, run module tests in a clean shell, run a script with modules loaded, print paths. |
+| `build`, `apply`, `status` | Build a release, build and install it, compare the active release with the build. |
+| `install`, `release list\|use\|rollback\|prune\|verify`, `uninstall` | Manage installed releases. |
+| `init`, `doctor` | Print the startup snippet; diagnose the installation. |
+| `compile`, `registry`, `explain-bundles`, `explain-variant`, `layer-lint`, `make-manifest` | Inspect and debug a build. |
 
-- [docs/installation.md](docs/installation.md) — install paths, shell
-  integration, XDG layout, publishing, and the integrity and provenance limits.
-- [docs/module-abi.md](docs/module-abi.md) — the metadata contract: fields,
-  allowed values, multi-root search path, runtime detection, side-effect
-  phases, and the capability layer.
-- [docs/architecture.md](docs/architecture.md) — what this repository
-  provides and what stays in the consuming project.
-- [docs/variants.md](docs/variants.md) — build variant selection and
-  exclusion lists.
-- [docs/contrib-modules.md](docs/contrib-modules.md) — module authoring
-  reference.
-- [docs/shared-modules.md](docs/shared-modules.md) — governance and index
-  for shared modules: namespace ownership, review, deprecation, removal.
-- [docs/release-policy.md](docs/release-policy.md) — compatibility surfaces,
-  current pre-1.0 status, and the release checklist.
-- [CHANGELOG.md](CHANGELOG.md) — user-facing changes.
-
-## Running the tests
-
-The Makefile and the test suite live in the source repository. The npm
-package ships the runtime, the docs, and the examples, not the Makefile.
+`valise <command> --help` prints each command's contract.
 
-```sh
-make check-fast  # quick contributor lane; no optional shells required
-make check       # available shell/runtime checks, CLI and end-to-end tests
-```
+## Documentation
 
-Strict mode requires the parsers declared in
-`manifests/parser-support.tsv`, the host shells used by the end-to-end lanes
-(`sh`, `bash`, `zsh`, `ksh`, `dash`, and `fish`), and a BusyBox executor.
-Missing tools skip with a visible message in an ordinary local run;
-`CI=true` or `GITHUB_ACTIONS=true` makes them fail. Lima VM lanes are optional
-and run only when the relevant instance is configured.
-To require the standard runtime set locally, run:
+- [docs/projects.md](docs/projects.md): the project layout, bundles,
+  variants, compile, and build.
+- [docs/contrib-modules.md](docs/contrib-modules.md): writing, linting, and
+  testing modules.
+- [docs/module-abi.md](docs/module-abi.md): every metadata field and what
+  the plans do with it.
+- [docs/installation.md](docs/installation.md): installing the CLI, startup
+  files, published commands, the release store, and uninstalling.
+- [docs/architecture.md](docs/architecture.md): how the pieces fit and what
+  stays in your project.
+- [docs/shared-modules.md](docs/shared-modules.md): layers other people
+  consume.
+- [docs/release-policy.md](docs/release-policy.md): compatibility and the
+  release checklist.
+- [examples/](examples/README.md): a sample project, a multi-shell test
+  project, and a sample provider layer.
+- [CHANGELOG.md](CHANGELOG.md)
+
+## Development
 
 ```sh
-make VALISE_REQUIRE_TOOLING=1 check
+make check-fast  # quick lane; no optional shells required
+make check       # every available shell and runtime lane
 ```
 
-To intentionally use non-strict behavior in CI, or require tools on a local
-machine, the GNU Make command-line override takes precedence. The Makefile
-also includes an optional untracked `config.mk` before its defaults, so
-machine-local preferences can be set there; use `VALISE_REQUIRE_TOOLING ?= 1`
-for a default that a command-line assignment can still override. The release
-checklist is in [docs/release-policy.md](docs/release-policy.md).
+`make check` uses the parsers in `manifests/parser-support.tsv`, the shells
+`sh`, `bash`, `zsh`, `ksh`, `dash`, and `fish`, and BusyBox. A missing tool
+is a visible skip locally and a failure when `CI=true` or
+`GITHUB_ACTIONS=true`; `make VALISE_REQUIRE_TOOLING=1 check` requires them
+locally. Machine-local settings go in an untracked `config.mk` (see
+`config.mk.example`). Lima VM lanes run only when the instances exist.