valise-sh 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,14 +3,175 @@
 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
+## [Unreleased]
 
-- Made the editor-defaults test independent of host-installed editors by
+## [0.2.0] - 2026-10-31
+
+### Added
+
+- `valise new`, `valise module new`, `valise module list`,
+  `valise module remove`, `valise build`, `valise apply`, and
+  `valise status`. A new project can be scaffolded, given a module, built,
+  installed, and checked without hand-writing a registry or a build script.
+  `valise module new` writes the module body and its declared export, and
+  wires the module into the seed aggregator. `valise apply` builds, installs,
+  writes the shell integration, and verifies the result; it is idempotent.
+  `valise status` reports the project, the active release, the integration
+  state, and whether the active release has drifted from the build output.
+- `valise registry`, which generates `shell/release/module-registry.tsv` from
+  the project's metadata. `valise build` regenerates and validates the
+  registry, so a committed registry is a generated artifact rather than a
+  hand-maintained catalog. The row order is fixed: the primary modules of
+  `shell/module.d/` first, then the layer modules of each
+  `shell/layers/<provider>/module.d/`, each group in C-locale name order.
+- `valise release list`, `valise release use`, `valise release prune`, and
+  `valise release verify`. They manage installed releases; source variants
+  remain the business of `valise build` and `valise apply`.
+- Command-specific `--help` for `build`, `compile`, `install`, `init`, `new`,
+  `module`, `release`, `doctor`, and `status`, so each prints its own
+  contract rather than the global command list.
+- Meta modules: metadata with `requires=` and no `load` is a
+  dependency-only aggregator and loads successfully without a body. `load`
+  and `requires` may be combined.
+- `side_effect=local-state`, a source-safe side-effect class for modules
+  that write under the XDG state directory.
+- `VALISE_RELOAD=1`, which unsets the declared exports of the requested
+  closure before loading so a profile can be re-sourced.
+- The `sp_cap_*` capability helpers remain available at runtime after a
+  compiled plan or a loader load finishes, so a module can call them.
+- `examples/profile-project/`, a complete consuming project with two
+  modules, a provider layer, two variants, and a bundle, and a README that
+  walks from clone to a loaded profile.
+- A consumer end-to-end test target that builds the reference consumer
+  profile from a temporary copy, runs the consumer's own metadata, shells,
+  release, and features suites, installs and verifies the release, and
+  proves a second build is byte-identical. The original tree and the live
+  profile are never touched.
+
+### Changed
+
+- `valise build` builds a complete release tree to `build/release` by
+  default, reads the variant and bundle defaults from
+  `shell/release/project.conf`, and requires an explicit output directory to
+  be empty or absent. A failed build preserves the previous build output.
+- `valise build` produces no Fish surface: no Fish entrypoint, generated
+  plan, or native loader. A built release therefore loads nothing in Fish;
+  the Fish hook verifies the active release and stays silent. Only an engine
+  release with `entrypoints/fish/profile.fish` uses the native Fish loader.
+- `valise install` writes shell integration by default. It always writes
+  `~/.profile`; it adds `~/.bash_profile` or `~/.bash_login` when one of
+  those exists, because bash reads that file instead of `~/.profile`; it
+  writes `~/.bashrc` when bash is the current shell or that file exists; it
+  writes `~/.zprofile` when zsh is on `PATH` or that file exists, because zsh
+  reads nothing else at login; and it writes `~/.zshrc` when zsh is the
+  current shell or that file exists. Existing files are kept current rather
+  than replaced. A symlinked startup file is reported and left untouched.
+  `--no-integration` installs without writing any startup file. Install also
+  writes the Fish `conf.d` hook when it finds Fish in a trusted location;
+  `valise apply` runs the same install path.
+- The startup integration is a managed block between `# BEGIN valise managed
+  block` and `# END valise managed block`. Repeat installs are idempotent and
+  existing profile content is preserved. An unpaired marker is refused and
+  stops the install. Install prints each path it wrote and how to remove the
+  block.
+- `valise init` takes `posix` or `fish`; any other argument is rejected.
+  It is a one-time snippet generator, not something to evaluate at every
+  prompt.
+- A project's default variant is `default`. An unknown variant is an error
+  in every command that accepts one.
+- Compiled plans and the loader now agree on required dependency closure.
+  Platform skips are recorded during discovery and reported once the full
+  required closure is known; strict mode fails when a required module is
+  blocked during ordering; permissive mode continues and returns zero. Fish
+  reports a platform-skipped optional dependency silently.
+- Compiled plans reach parity with the loader: they gate modules by
+  `platforms=` at runtime, pre-check and post-check declared exports, report
+  each failing module by name, continue past a failure in permissive mode
+  while returning zero, stop in strict mode, and support meta modules with no
+  source line.
+- The loader saves the logical `$PWD` and `$OLDPWD` before sourcing each
+  module and restores them afterwards, so a module that changes directory
+  during its load leaves the caller's logical directory as it was.
+- The loader's export pre-check accepts a name that currently resolves to an
+  external command, which is how a deliberate wrapper is exported. It still
+  rejects a name already defined as a function, builtin, or alias.
+- The loader resolves each metadata record with shell builtins instead of
+  repeated `sed`, `grep`, and `cat` processes, so the number of external
+  processes a load spawns does not grow with the number of modules.
+- `valise compile` and `valise build` find the packaged
+  `lib/capabilities.sh` relative to the CLI, so a symlinked or relocated
+  install works. A compiled plan rejects a module that has neither a load
+  path nor dependencies, and names the module.
+- Layer handling accepts any `shell/layers/<provider>` path rather than only
+  the `contrib` provider, and produces a deterministic manifest.
+- `valise doctor` reports a missing active release as a failure and reads the
+  startup files the running shell actually reads. `--pre-install` skips the
+  release and integration checks; `--no-integration` checks only the
+  environment and the active release.
+- `valise explain-bundles` and `valise layer-lint` are implemented in POSIX sh
+  and awk. `layer-lint` validates a provider layer's structure, `contrib_`
+  name prefix, version, load path, symlink freedom, file modes, and
+  dependency containment.
+- The unused Python consumer-release helpers, wrapper lifecycle hooks, and
+  the submodule build prelude override are gone. No command requires
+  Python 3.
+
+### Removed
+
+- `load_hook` and the compatibility bridge in the POSIX loader, the Fish
+  loader, and compiled plans. A module declares `load`, `requires`, or both.
+  Metadata naming `load_hook` fails with
+  `metadata field load_hook is not supported; use load`.
+- `variant list`, `variant use`, and `verify-active`; installed releases are
+  managed by `valise release list|use|prune|verify`. `variant` now refers
+  only to build variants.
+- The per-shell `valise init` arguments `bash`, `zsh`, `ksh`, and `sh`; use
+  `valise init posix` or `valise init fish`.
+
+### Fixed
+
+- `valise` with no arguments: under `set -e`, a zero-argument `shift` could
+  terminate the CLI before it displayed its help text.
+- Fish activation: functions loaded from package paths such as Homebrew are
+  authenticated and preserved through the load instead of being rejected or
+  lost.
+- The primary-root symlink diagnostic was printed on stdout while every
+  other loader diagnostic went to stderr.
+- `valise compile` reported that a Fish plan requires a Python compiler and
+  named a file that does not exist in this repository. Fish plans are not
+  generated; a Fish integration uses the native Fish loader.
+- Applying to a home directory with a trailing slash could skip the zsh
+  startup file, because the target was compared against the raw `HOME`
+  string rather than a normalized path.
+- A built release's Fish hook printed an error on every Fish start. It now
+  verifies the release quietly and returns when there is no Fish surface to
+  load.
+- A module that makes `PWD`, `OLDPWD`, or `IFS` readonly no longer aborts the
+  loader mid-transaction. The module fails as caller-state modification, and
+  the loader's cleanup still runs.
+- Loader temp-directory cleanup resolves `rm` from a fixed absolute path, so a
+  module that changes `PATH` cannot leave its metadata scratch directory
+  behind.
+- Compiled plans remove a failed module's declared exports, like the loader.
+  A meta module that declares exports is rejected at compile time, and an
+  optional-only cycle inside a required graph is quarantined instead of
+  failing the whole plan.
+- The compiler rejects an unsafe layer directory name and a reserved-word
+  export instead of emitting an unparseable or misleading plan.
+- `release list`, `release use`, `release prune`, `doctor`, and `status`
+  identify the active release by its canonical directory name, so a trailing
+  slash or an alias symlink cannot hide it from the list or make prune delete
+  it.
+- `module remove` keeps a body that another module still loads, and checks
+  every directory it will rewrite before changing anything. `module new`
+  checks the seed metadata before writing and rejects reserved-word exports.
+- `make-manifest` rejects a directory or symlink as its output, and a
+  normalized in-tree output path is excluded from its own manifest.
+- `valise install` holds its lock through the Fish and POSIX integration
+  writes, so concurrent installs cannot interleave them.
+- The editor-defaults test is independent of host-installed editors by
   supplying a temporary test `vi` executable.
-- Fixed `valise` with no arguments: under `set -e`, a zero-argument `shift`
-  could terminate the CLI before it displayed its help text.
-- Fixed Fish activation so functions loaded from package paths (for example,
-  Homebrew) are authenticated and preserved through the load instead of being
-  rejected or lost.
-- Added an isolated sample install walkthrough and documented the release
-  checklist.
+
+[Unreleased]: https://github.com/joeycumines/valise-sh/compare/v0.2.0...HEAD
+[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

@@ -42,29 +42,44 @@ export PATH="$PWD/bin:$PATH"
   export XDG_CONFIG_HOME="$_demo_state/config"
   export XDG_STATE_HOME="$_demo_state/state"
 
-  # Build, install, and verify the sample release.
-  sh examples/e2e/build-manifest.sh
-  (cd examples/e2e && valise install)
-  valise verify-active
-
-  # Load two shipped utilities from the installed release.
-  _active=$(cd "$XDG_CONFIG_HOME/valise/active" && pwd -P)
-  VALISE_MODULE_ROOT="$_active" \
-    VALISE_MODULES='contrib_path contrib_editor' \
-    VALISE_MODE=strict \
-    . "$_active/entrypoints/profile.sh"
-  contrib_path_prepend "$HOME/.local/bin"
-  contrib_editor_defaults
-  printf 'EDITOR=%s\nPATH=%s\n' "${EDITOR-(unset: no supported editor found on PATH)}" "$PATH"
+  # 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'
 )
 ```
 
-The end-to-end example documents Fish startup, shared-provider composition,
-and other modules in
+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
+
+The sample above loads modules from an example profile. To build your own,
+start from the project scaffold:
+
+```sh
+export PATH="$PWD/bin:$PATH"
+valise new my-profile
+cd my-profile
+```
+
+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:
+
+```sh
+valise build   # build a release under build/release/
+valise apply   # install it and write the managed shell integration
+```
+
+`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
@@ -79,14 +94,16 @@ loader example without installation, use `examples/local/` as described in
   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, doctor, variant, make-manifest,
-  compile, verify-active, explain-variant, explain-bundles, layer-lint,
-  version. `init`, `install`, `doctor`, `variant`, `make-manifest`,
-  `verify-active`, and `version` run from a bare checkout; `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).
+- `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
@@ -95,6 +112,10 @@ loader example without installation, use `examples/local/` as described in
   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
@@ -121,6 +142,9 @@ transactions belong in the consuming project, not here. See
 
 ## 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.
+
 ```sh
 make check-fast  # quick contributor lane; no optional shells required
 make check       # available shell/runtime checks, CLI and end-to-end tests