valise-sh 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,177 @@
+# Changelog
+
+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.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.
+
+[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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Cumines
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# valise-sh
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+```sh
+git clone https://github.com/joeycumines/valise-sh.git
+cd valise-sh
+export PATH="$PWD/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'
+)
+```
+
+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
+  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.
+
+## Documentation
+
+- [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.
+
+```sh
+make check-fast  # quick contributor lane; no optional shells required
+make check       # available shell/runtime checks, CLI and end-to-end tests
+```
+
+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:
+
+```sh
+make VALISE_REQUIRE_TOOLING=1 check
+```
+
+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).