valise-sh 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/CHANGELOG.md +320 -9
  2. package/README.md +104 -127
  3. package/bin/valise +67 -3266
  4. package/docs/architecture.md +76 -51
  5. package/docs/contrib-modules.md +180 -173
  6. package/docs/installation.md +210 -69
  7. package/docs/module-abi.md +211 -148
  8. package/docs/projects.md +249 -0
  9. package/docs/release-policy.md +90 -11
  10. package/docs/shared-modules.md +149 -26
  11. package/examples/README.md +20 -8
  12. package/examples/e2e/README.md +61 -68
  13. package/examples/e2e/bundles.tsv +6 -0
  14. package/examples/e2e/module.d/e2e_aliases.meta +1 -2
  15. package/examples/e2e/module.d/e2e_completions_bash.meta +0 -1
  16. package/examples/e2e/module.d/e2e_completions_zsh.meta +0 -1
  17. package/examples/e2e/module.d/e2e_env_setup.meta +2 -3
  18. package/examples/e2e/module.d/e2e_fish_features.meta +0 -1
  19. package/examples/e2e/module.d/e2e_generated_config.meta +1 -2
  20. package/examples/e2e/module.d/e2e_ksh_features.meta +0 -1
  21. package/examples/e2e/module.d/e2e_layer_probe.meta +1 -2
  22. package/examples/e2e/module.d/e2e_optional_network.meta +1 -2
  23. package/examples/e2e/module.d/e2e_platform_tools.meta +8 -0
  24. package/examples/e2e/module.d/e2e_platform_tools_bsd.meta +2 -3
  25. package/examples/e2e/module.d/e2e_platform_tools_darwin.meta +2 -3
  26. package/examples/e2e/module.d/e2e_platform_tools_linux.meta +2 -3
  27. package/examples/e2e/valise.conf +4 -0
  28. package/examples/e2e/variants.tsv +3 -0
  29. package/examples/local/module.d/hello_valise.meta +1 -2
  30. package/examples/profile-project/README.md +151 -0
  31. package/examples/profile-project/bundles.tsv +8 -0
  32. package/examples/profile-project/layers/demo/module.d/contrib_demo_greeting.meta +9 -0
  33. package/examples/profile-project/layers/demo/modules/shared/contrib_demo_greeting.sh +4 -0
  34. package/examples/profile-project/module.d/greeting.meta +9 -0
  35. package/examples/profile-project/module.d/profile_main.meta +8 -0
  36. package/examples/profile-project/modules/greeting.sh +5 -0
  37. package/examples/profile-project/valise.conf +4 -0
  38. package/examples/profile-project/variants.tsv +3 -0
  39. package/examples/shared/README.md +13 -34
  40. package/examples/shared/module.d/contrib_shared_paths.meta +2 -3
  41. package/examples/shared/module.d/contrib_shared_umask.meta +1 -2
  42. package/examples/shared/modules/shared/contrib_shared_paths.sh +2 -2
  43. package/lib/capabilities.sh +40 -13
  44. package/lib/cli/commands.sh +278 -0
  45. package/lib/cli/common.sh +326 -0
  46. package/lib/cli/devtools.sh +539 -0
  47. package/lib/cli/fish-hook.sh +986 -0
  48. package/lib/cli/integration.sh +337 -0
  49. package/lib/cli/lifecycle.sh +578 -0
  50. package/lib/cli/project.sh +1807 -0
  51. package/lib/cli/store.sh +1023 -0
  52. package/lib/cli/usage.sh +308 -0
  53. package/lib/compiler.awk +352 -24
  54. package/lib/fish/loader.fish +163 -28
  55. package/lib/fish/metadata.fish +62 -19
  56. package/lib/fish/profile.fish +170 -0
  57. package/lib/loader.sh +736 -158
  58. package/lib/metadata.sh +137 -55
  59. package/manifests/parser-support.tsv +2 -2
  60. package/module.d/valise_editor.meta +9 -0
  61. package/module.d/valise_history.meta +9 -0
  62. package/module.d/valise_pager.meta +9 -0
  63. package/module.d/valise_path.meta +9 -0
  64. package/module.d/{platform_bsd.meta → valise_platform_bsd.meta} +3 -4
  65. package/module.d/{platform_linux.meta → valise_platform_linux.meta} +3 -4
  66. package/module.d/{platform_macos.meta → valise_platform_macos.meta} +3 -4
  67. package/module.d/{platform_posix.meta → valise_platform_posix.meta} +2 -3
  68. package/module.d/valise_xdg.meta +9 -0
  69. package/modules/system/{contrib_editor.sh → valise_editor.sh} +2 -2
  70. package/modules/system/{contrib_history.sh → valise_history.sh} +2 -2
  71. package/modules/system/{contrib_pager.sh → valise_pager.sh} +2 -2
  72. package/modules/system/{contrib_path.sh → valise_path.sh} +3 -3
  73. package/modules/system/{contrib_xdg.sh → valise_xdg.sh} +2 -2
  74. package/package.json +91 -9
  75. package/docs/variants.md +0 -63
  76. package/entrypoints/.gitkeep +0 -0
  77. package/entrypoints/fish/profile.fish +0 -99
  78. package/examples/e2e/build-manifest.sh +0 -250
  79. package/examples/local/.gitkeep +0 -0
  80. package/lib/.gitkeep +0 -0
  81. package/manifests/.gitkeep +0 -0
  82. package/module.d/.gitkeep +0 -0
  83. package/module.d/contrib_editor.meta +0 -10
  84. package/module.d/contrib_history.meta +0 -10
  85. package/module.d/contrib_pager.meta +0 -10
  86. package/module.d/contrib_path.meta +0 -10
  87. package/module.d/contrib_xdg.meta +0 -10
  88. package/modules/.gitkeep +0 -0
@@ -0,0 +1,249 @@
1
+ # Projects, bundles, variants, and builds
2
+
3
+ This document describes a valise project: the files it contains, how
4
+ `valise compile` and `valise build` turn them into plans and a release, and
5
+ how those commands fail. [module-abi.md](module-abi.md) covers the metadata
6
+ format; [installation.md](installation.md) covers what happens to a release
7
+ once it is built.
8
+
9
+ ## The project layout
10
+
11
+ A project is a directory that holds `valise.conf`:
12
+
13
+ ```
14
+ valise.conf project settings
15
+ module.d/ primary modules: <name>.meta
16
+ modules/ primary module bodies (any layout below modules/)
17
+ layers/<provider>/ vendored provider layers (optional)
18
+ module.d/ layer modules: contrib_<name>.meta
19
+ modules/ layer module bodies
20
+ bundles.tsv the root modules of each bundle, per shell
21
+ variants.tsv build variants and what each leaves out (optional)
22
+ build/ build output; keep it out of version control
23
+ ```
24
+
25
+ `valise new [dir]` writes this layout with a POSIX seed module
26
+ `profile_main`, a Fish seed module `profile_main_fish`, a `bundles.tsv` with
27
+ `sh`, `bash`, `zsh`, `ksh`, and `fish` rows, `variants.tsv`, and a
28
+ `.gitignore` for `build/`.
29
+
30
+ Project commands find the project by walking up from the working directory to
31
+ the first directory that holds `valise.conf`. `valise -C <dir> <command>` runs
32
+ a command as if it had been started in `dir`.
33
+
34
+ `valise.conf` has one `key=value` per line. Blank lines and `#` comments are
35
+ ignored; an unknown or repeated key is an error.
36
+
37
+ | Key | Meaning |
38
+ |---|---|
39
+ | `bundle` | Default bundle for build, apply, compile, and run (default `default`). |
40
+ | `variant` | Default variant (default `default`). |
41
+ | `requires_valise` | Oldest valise version that may build the project, such as `0.3.0`. An older valise refuses with `this project requires valise >= ...`. |
42
+ | `lint_layer_forbid` | Extended regular expression that must not match anything under `layers/` (case-insensitive). `valise lint` enforces it; use it to keep personal or employer material out of a layer you share. |
43
+
44
+ A layer's directory name is made of letters, digits, `_`, `-`, and `.`, and
45
+ may not start with `.` or contain `..`. Metadata and bodies must be regular
46
+ files reached without a symlink.
47
+
48
+ ## Modules and the registry
49
+
50
+ The `.meta` files are the only source of truth. valise reads them as data,
51
+ never by sourcing them. Each build collects three groups of modules:
52
+
53
+ 1. the project's `module.d/`, with source `module.d`;
54
+ 2. each `layers/<provider>/module.d/`, with source
55
+ `layers/<provider>/module.d`;
56
+ 3. the engine's own modules, with source `valise`.
57
+
58
+ The engine modules (`valise_path`, `valise_editor`, `valise_history`,
59
+ `valise_pager`, `valise_xdg`, and the `valise_platform_*` modules) are always
60
+ available. They ship in a release only when the release loads them. The
61
+ `valise_` prefix is reserved for them, and every layer module must use the
62
+ `contrib_` prefix.
63
+
64
+ `valise registry [path]` prints the table valise builds from these files, for
65
+ inspection. It is internal: nothing reads a saved copy, so do not commit one.
66
+ The table is tab-separated, with one header row and one row per module, in
67
+ a fixed order: primary modules, then each layer, then the engine, each in
68
+ C-locale name order.
69
+
70
+ | # | Column | Meaning |
71
+ |---|---|---|
72
+ | 1 | `name` | Module identifier. |
73
+ | 2 | `version` | Version string; empty means unversioned. |
74
+ | 3 | `side_effect` | Side-effect class. |
75
+ | 4 | `requires` | Required dependencies. |
76
+ | 5 | `optional` | Optional dependencies. |
77
+ | 6 | `shells` | Shell classes. |
78
+ | 7 | `platforms` | Platforms. |
79
+ | 8 | `exports` | Exported functions. |
80
+ | 9 | `load` | Body path relative to the module's source directory; empty for a meta module. |
81
+ | 10 | `commands` | Exports published as commands. |
82
+ | 11 | `executables` | Scripts published as commands. |
83
+ | 12 | `tests` | Test scripts for `valise test`. |
84
+ | 13 | `source` | `module.d`, `layers/<provider>/module.d`, or `valise`. |
85
+
86
+ Building the table also validates it. A `name` that differs from its file
87
+ name, a missing body, executable or test, a symlink, a misplaced prefix, or
88
+ invalid metadata stops the command and names the file.
89
+
90
+ A module reference is a bare name or a qualified `name@source`. A bare
91
+ dependency resolves to the module with that name in the same source when
92
+ there is one, otherwise to the only module with that name. A bare bundle root
93
+ or exclusion resolves to the primary module when there is one, otherwise to
94
+ the only module with that name; when several sources define the name, qualify
95
+ it.
96
+
97
+ ## Bundles: the root modules for each shell
98
+
99
+ `bundles.tsv` is tab-separated: bundle, shell, and a space-separated list of
100
+ root modules. The first row may be a header.
101
+
102
+ ```
103
+ bundle shell roots
104
+ default sh profile_main
105
+ default bash profile_main profile_bash
106
+ default zsh profile_main
107
+ default ksh profile_main
108
+ default fish profile_main_fish
109
+ work bash profile_main profile_work
110
+ ```
111
+
112
+ The shell column is one of `sh`, `bash`, `zsh`, `ksh`, and `fish`. `sh` is the
113
+ plan for any POSIX shell that is not bash, zsh, or ksh, such as dash or
114
+ BusyBox ash. A bundle without a row for a shell loads nothing there.
115
+
116
+ Roots are starting points. The plan loads each root's whole closure of
117
+ `requires` and available `optional` dependencies, in dependency order.
118
+ `valise explain-bundles [--bundle=<name>] [--variant=<name>]` prints each
119
+ bundle's roots and ordered closure per shell, with each module's source.
120
+
121
+ A root, and every module it requires, must support the shell and the
122
+ platform it runs on: in strict mode an unsupported platform is a failure. A
123
+ module that exists only for some platforms belongs behind an optional edge.
124
+ Write an aggregator whose `optional=` lists the per-platform modules and use
125
+ the aggregator as the root; the module for the running platform loads, and
126
+ the others are skipped without a message.
127
+
128
+ ## Variants: what to leave out
129
+
130
+ `variants.tsv` is tab-separated: variant name, description, and a
131
+ space-separated list of excluded modules. Without the file, the only variant
132
+ is `default`, which excludes nothing.
133
+
134
+ ```
135
+ variant description excluded
136
+ default All project modules
137
+ lean No editor defaults valise_editor
138
+ ```
139
+
140
+ Each exclusion must resolve to exactly one module; an unknown or ambiguous
141
+ exclusion is an error. An excluded module is removed from every closure, and
142
+ its optional edges are dropped. **If a remaining module requires an excluded
143
+ module, the build fails**, naming both; exclude the dependents too. Nothing is
144
+ removed silently.
145
+
146
+ `valise explain-variant [--bundle=<name>] [name]` shows a variant's
147
+ description, its exclusions, and how many of the bundle's roots it removes
148
+ per shell. The bundle chooses the roots, and the variant then removes
149
+ modules from what they reach.
150
+
151
+ ## `valise compile`
152
+
153
+ ```sh
154
+ valise compile [--bundle=<name>] [--variant=<name>] <output-dir>
155
+ ```
156
+
157
+ Compile writes `<output-dir>/<shell>.sh` for each POSIX shell the bundle has
158
+ roots for, and nothing else. The output directory must be empty or absent;
159
+ compile stages beside it and publishes only after every plan compiled.
160
+
161
+ A plan is a POSIX shell file:
162
+
163
+ ```
164
+ # valise-plan-v2
165
+ # Generated by valise compile; DO NOT EDIT.
166
+ # plan=bash
167
+ # roots=profile_main
168
+ # order=valise_path profile_main
169
+ ```
170
+
171
+ The header names the format, the shell, the roots, and the resolved load
172
+ order. Sourced with `VALISE_MODULE_ROOT` naming a release, the plan:
173
+
174
+ - reads `VALISE_MODE` (`strict` or `permissive`; default `strict`);
175
+ - probes the platform once and gates each module by `platforms=`;
176
+ - sources `runtime/capabilities.sh`, so the `sp_cap_*` helpers stay available
177
+ to module functions afterwards;
178
+ - refuses to load a module whose declared export already exists as an alias,
179
+ function, or builtin (an export may shadow a command on PATH), and checks
180
+ after loading that each export is defined;
181
+ - skips a module whose required dependency failed or was skipped, and says
182
+ which;
183
+ - in strict mode, returns nonzero at the first failure among the roots and
184
+ everything they require;
185
+ - in permissive mode, reports each failure, continues with unrelated
186
+ modules, and returns zero;
187
+ - loads an optional dependency first when it can; its absence never affects
188
+ the module that declared it;
189
+ - with `VALISE_RELOAD=1`, removes the plan's declared exports first, so the
190
+ plan can be sourced again.
191
+
192
+ Compile fails before writing anything when the variant or bundle is unknown,
193
+ an exclusion or root does not resolve, a variant exclusion breaks a required
194
+ dependency, a module in a closure has a side-effect class that is not safe at
195
+ startup (`generated-file`, `update-network`, or `install-time`), or a module
196
+ is not representable as plan source.
197
+
198
+ ## `valise build`
199
+
200
+ ```sh
201
+ valise build [--bundle=<name>] [--variant=<name>] [out]
202
+ ```
203
+
204
+ Build produces an installable release tree at `build/release`, or at `out`,
205
+ which must then be empty or absent. The tree contains:
206
+
207
+ ```
208
+ valise-release.conf format=2, valise_version, bundle, variant,
209
+ roots_<shell>=, modules=, commands=
210
+ manifest.tsv the release manifest
211
+ plans/<shell>.sh one plan per POSIX shell with roots
212
+ plans/commands/<module>.sh a plan per module that publishes commands
213
+ bin/<command> command launchers and executables
214
+ runtime/capabilities.sh the capability prelude
215
+ runtime/fish/{metadata,loader,profile}.fish when the bundle has fish roots
216
+ module.d/, modules/... primary modules some shell loads
217
+ layers/<provider>/module.d, ... layer modules some shell loads
218
+ valise/module.d, valise/modules/... engine modules some shell loads
219
+ ```
220
+
221
+ Only modules in some shell's closure are copied, with their metadata. A
222
+ module that a variant excludes, or that no root reaches, is absent from the
223
+ release, together with its body. The Fish runtime resolves the Fish roots
224
+ recorded in `valise-release.conf` against the copied metadata when Fish
225
+ starts. See [module-abi.md](module-abi.md#published-commands) for `bin/`.
226
+
227
+ Directories are `0755`, files `0644`, and `bin/` entries `0755`. Build
228
+ stages beside the destination and publishes only after the tree and its
229
+ manifest are complete. A previous `build/release` is moved aside first and
230
+ put back if publication fails, so a failed build leaves the previous output
231
+ in place. Building the same project twice produces byte-identical output.
232
+
233
+ ## `valise apply` and `valise status`
234
+
235
+ `valise apply [--bundle=<name>] [--variant=<name>] [--no-integration]
236
+ [--dry-run]` builds to `build/release`, installs it, writes the shell
237
+ integration and command stubs, and verifies the active release. Running it
238
+ again changes nothing. `--dry-run` stops after the build and prints what
239
+ install would change; see [installation.md](installation.md).
240
+
241
+ `valise status` reports the project defaults, the integration in each startup
242
+ file, the bundle, variant, and valise version the active release was built
243
+ with, and whether the active release matches `build/release`.
244
+
245
+ ## Checking a project
246
+
247
+ `valise lint` and `valise test` check a project without installing it, and
248
+ `valise run` loads modules into a throwaway shell; see
249
+ [contrib-modules.md](contrib-modules.md#checking-and-testing-modules).
@@ -2,9 +2,11 @@
2
2
 
3
3
  ## Current status
4
4
 
5
- `valise-sh` is at **0.1.0**. Before 1.0, the CLI, module ABI, and release
6
- format do not have a backward-compatibility guarantee. Consumers should pin
7
- updates, review release notes, and run their profile's tests before upgrading.
5
+ `valise-sh` is at **0.3.0**. Before 1.0, the CLI, module ABI, and release
6
+ format do not have a backward-compatibility guarantee. Pin the version you
7
+ use, read the release notes, and run `valise lint` and `valise test` on your
8
+ project before upgrading. A project can set `requires_valise=` in
9
+ `valise.conf` so an older valise refuses to build it.
8
10
 
9
11
  ## Compatibility surface
10
12
 
@@ -19,26 +21,94 @@ The compatibility contract has three separate parts:
19
21
 
20
22
  A change affecting one of these is a compatibility change even if the other
21
23
  surfaces remain unchanged. Before 1.0, incompatible changes may occur between
22
- minor releases; release notes must identify affected consumers and migration
23
- steps. After 1.0, use semantic versioning: patch for compatible fixes,
24
+ minor releases, and release notes must state what consumers have to change.
25
+ After 1.0, use semantic versioning: patch for compatible fixes,
24
26
  minor for backward-compatible features, and major for incompatible changes.
25
27
 
28
+ ## What changed in 0.3.0
29
+
30
+ 0.3.0 changes the project layout, the metadata, the release format, and the
31
+ startup block. A 0.2 project does not build until it is moved to the new
32
+ layout, and a 0.2 release cannot be installed; rebuild it. Every change is
33
+ also in [CHANGELOG.md](../CHANGELOG.md).
34
+
35
+ ### Moving a 0.2 project
36
+
37
+ | 0.2 | 0.3 |
38
+ |---|---|
39
+ | `shell/module.d/`, `shell/modules/` | `module.d/`, `modules/` at the project root |
40
+ | `shell/layers/<p>/` | `layers/<p>/` |
41
+ | `shell/release/bundle-roots` | `bundles.tsv` (bundle, shell, roots) |
42
+ | `shell/release/install-variants` | `variants.tsv` (variant, description, excluded) |
43
+ | `shell/release/project.conf` | `valise.conf` (`bundle=`, `variant=`, `requires_valise=`, `lint_layer_forbid=`) |
44
+ | `shell/release/module-registry.tsv` | nothing: the registry is internal; delete the file |
45
+ | `valise registry --check` | nothing: `valise lint` checks the metadata |
46
+ | `@shell/layers/<p>/module.d` in a qualified name | `@layers/<p>/module.d` |
47
+
48
+ valise does not read the `shell/` layout: until `valise.conf` exists,
49
+ project commands report that they are not inside a valise project.
50
+
51
+ ### Metadata
52
+
53
+ - `shells=posix` means every POSIX shell. `shells=sh` now means only the
54
+ generic class (dash, BusyBox ash, and other plain `sh`), so a module that
55
+ used `shells=sh` for "all POSIX shells" must change to `shells=posix`.
56
+ - `updates=` is rejected. Remove it.
57
+ - A repeated field is rejected.
58
+ - The engine modules moved into the reserved `valise_` namespace:
59
+ `contrib_path` is now `valise_path` (exports `valise_path_prepend` and
60
+ `valise_path_append`), `contrib_editor`, `contrib_history`,
61
+ `contrib_pager`, and `contrib_xdg` are `valise_editor`, `valise_history`,
62
+ `valise_pager`, and `valise_xdg`, and `platform_<os>` is
63
+ `valise_platform_<os>`. Update `requires=` and the calls to their
64
+ exports.
65
+ - New fields: `commands=` publishes exports as commands on `PATH`,
66
+ `executables=` publishes scripts, and `tests=` names the scripts
67
+ `valise test` runs.
68
+
69
+ ### Releases and startup
70
+
71
+ - A release has one shape: `plans/<shell>.sh`, `runtime/`, `bin/`,
72
+ `valise-release.conf` with `format=2`, and `manifest.tsv`. It contains
73
+ only the modules some plan loads. The `generated/`, `vendor/`,
74
+ `shell/install/`, and engine-release (`entrypoints/`) shapes are gone, and
75
+ install refuses a tree without `format=2`.
76
+ - The POSIX block picks a plan for `ksh`, `zsh`, `bash`, or `sh` and has no
77
+ loader fallback. Run `valise apply` once to rewrite the block in each
78
+ startup file. Install warns about any line outside a managed block that
79
+ still loads a 0.2 release.
80
+ - A bundle's `fish` rows build the native Fish runtime into the release.
81
+
82
+ ### New commands
83
+
84
+ `valise lint`, `test`, `run`, `env`, `uninstall`, `release rollback`, and
85
+ `apply --dry-run`. Install is transactional: a failure puts the previous
86
+ active release back.
87
+
26
88
  ## Release checklist
27
89
 
28
90
  Before tagging or publishing a release:
29
91
 
30
- 1. Update `package.json` and `bin/valise` version together; add a dated entry
31
- to [CHANGELOG.md](../CHANGELOG.md).
92
+ 1. Update the `package.json` version and `VALISE_VERSION` in `bin/valise`
93
+ together; add a dated entry to [CHANGELOG.md](../CHANGELOG.md). The CLI's test suite asserts that the
94
+ two versions match, so a bump that updates one and forgets the other
95
+ fails the build.
32
96
  2. Run `make check-fast`, then run `make VALISE_REQUIRE_TOOLING=1 check`
33
97
  locally or use the GitHub Actions job. Keep the successful strict run as
34
98
  release evidence for every lane, including Fish, zsh, BusyBox, dash, and
35
99
  ksh.
36
- 3. Run the README isolated quickstart from a clean checkout and verify that
37
- install, `verify-active`, and example module loading work in the temporary
38
- home. Confirm cleanup removes the entire demo state.
100
+ 3. Run the README's scratch-home example from a clean checkout and check
101
+ that `greet` runs and the cleanup removes the scratch directory.
39
102
  4. Inspect the result of `npm pack --dry-run` and install/test the packed
40
103
  tarball. The CLI's tests currently cover pack contents, installation, and
41
- module loading.
104
+ module loading. The probe in `tests/cli-posix.test.sh` builds a tree from
105
+ the real `files` whitelist, plants build directories at more than one
106
+ depth under `examples/`, and requires the tarball to exclude every one of
107
+ them while keeping the surrounding example sources. `package.json` keeps
108
+ them out with `!examples/**/build/`, because npm applies `files` without
109
+ consulting `.gitignore` and `valise apply` writes build output into
110
+ `examples/profile-project/`. The `**` is load-bearing: a single `*` still
111
+ packs a build directory nested one level deeper.
42
112
  5. Review the changed CLI, module ABI, release manifest, docs, and examples;
43
113
  check `git diff --check` and doc links.
44
114
  6. Publish only through the chosen distribution channel. The repository
@@ -48,3 +118,12 @@ Before tagging or publishing a release:
48
118
 
49
119
  Do not claim a platform or shell has passed unless its runtime lane actually
50
120
  ran. An explicit skip is useful development evidence, not release evidence.
121
+
122
+ ## Test isolation
123
+
124
+ Every suite runs in a quarantined environment: a fresh temporary `HOME`,
125
+ controlled `TMPDIR` and `PATH`, and cleared startup hooks. A suite must also
126
+ pass when it is run directly rather than through `make`, because the Makefile
127
+ pins `TMPDIR=/tmp` and that can hide a defect that a developer's own
128
+ environment exposes. macOS sets `TMPDIR` to a path ending in a slash, so a
129
+ path comparison in a suite must resolve both sides before comparing them.
@@ -1,38 +1,157 @@
1
1
  # Shared modules: governance and index
2
2
 
3
3
  This policy covers the shared modules shipped here and the requirements for
4
- provider repositories. It defines the layer namespace, review expectations,
5
- and how modules are indexed, deprecated, and removed.
4
+ provider repositories. It defines the layer namespace, what belongs in a
5
+ layer, review expectations, and how modules are indexed, deprecated, and
6
+ removed.
6
7
 
7
8
  ## Namespace and ownership
8
9
 
9
- The loader enforces the layer namespace. This policy assigns ownership and
10
- review responsibility.
10
+ `valise build`, `valise lint`, and `valise layer-lint` enforce the layer
11
+ namespace. This policy assigns ownership and review responsibility.
11
12
 
12
- - Layer-only modules must use the `contrib_` prefix. The loader rejects
13
- other layer-only names (see [module-abi.md](module-abi.md)).
13
+ - Layer modules must use the `contrib_` prefix, and the `valise_` prefix
14
+ belongs to the engine (see [module-abi.md](module-abi.md#layers)).
14
15
  - Module names are owned by the tree that ships them. The engine
15
16
  repository owns every module under its `module.d/`. A provider
16
17
  repository owns every module in its layer tree.
17
- - A module with the same name in multiple roots must have matching metadata
18
- and body bytes. Different bytes or different `version=` values make the
19
- load fail with a diagnostic naming the providers. Identical copies resolve
20
- by root priority; providers should still agree on which tree owns the name.
18
+ - When two sources in a project define the same name, a bare bundle root
19
+ or exclusion naming it is ambiguous and the build fails until it is
20
+ qualified as `name@source`; a dependency resolves to its own source first. The Fish loader and the development loader accept several
21
+ providers of one name only when their metadata and bodies are
22
+ byte-identical. Either way, providers should agree on which tree owns a
23
+ name.
21
24
  - A provider repository that wants its modules consumed must document them
22
25
  in an index of its own, following this document's shape (name, version,
23
26
  exports, source, status). Consumers read the provider's index to
24
27
  discover what exists; they read this index to discover what the engine
25
28
  ships.
26
29
 
30
+ ### Use an owner segment
31
+
32
+ The `contrib_` prefix is the only part the tools enforce. Nothing
33
+ mechanically distinguishes one provider from another, so two providers that
34
+ both ship `contrib_path_utils` fail closed against each other with a
35
+ same-name conflict, and neither can be swapped for the other.
36
+
37
+ **Use a provider segment after the prefix: `contrib_<owner>_<thing>`.**
38
+
39
+ ```
40
+ contrib_acme_widget_setup
41
+ contrib_acme_widget_apply
42
+ contrib_globex_path_helpers
43
+ ```
44
+
45
+ This is a recommendation, not a rule the tools check, but it is what keeps
46
+ two providers from colliding. A layer should use one owner segment
47
+ consistently across all of its modules, so a consumer can see at a glance
48
+ which provider owns what.
49
+
50
+ If you must ship a module whose name another provider might already use,
51
+ prefix it with your owner segment anyway: a name collision between two
52
+ vendored providers is otherwise unresolvable without renaming one of them.
53
+
54
+ ## What belongs in a layer
55
+
56
+ A layer is a vendorable set of modules: something another person can take
57
+ unchanged, use, and maintain on their own terms. The practical test is
58
+ simple: **could another person vendor this module unchanged and still be
59
+ happy with it?**
60
+
61
+ A layer module must have:
62
+
63
+ - **No employer material.** No account IDs, hostnames, cloud profiles,
64
+ project names, or anything else tied to one organization.
65
+ - **No personal configuration.** No hard-coded home paths, no chosen
66
+ editor, no particular toolchain, model, or theme.
67
+ - **No dependency outside the layer**, apart from the engine's own modules.
68
+ A layer module may require an engine module, but it may not require a
69
+ module that lives in the consumer's primary root, because that dependency cannot
70
+ be satisfied when someone else vendors the layer.
71
+
72
+ Everything else stays in the primary root: environment setup, completions,
73
+ tool wrappers, work-specific modules, and the aggregators.
74
+
75
+ `valise layer-lint <layer-name>` and `valise lint` enforce the mechanical
76
+ half of this. It
77
+ checks that the layer has a `module.d/` directory, that every metadata file
78
+ is a regular file with a safe mode, that every module name carries the
79
+ `contrib_` prefix, that the metadata validates as data, that the version is
80
+ present, that the load target exists as a regular file, and that every
81
+ dependency resolves inside the layer or to an engine module. Set
82
+ `lint_layer_forbid` in `valise.conf` to make `valise lint` reject named
83
+ identifiers, such as an employer's, anywhere under `layers/`.
84
+
85
+ ### 1. Separate generic engines from opinionated presets
86
+
87
+ A reusable mechanism and the opinionated defaults built on it are different
88
+ modules with different audiences, and they belong in different files.
89
+
90
+ The engine is the part anyone might want. The preset is a list of specific
91
+ choices that only some users want. Ship them as two modules so a consumer
92
+ can take the engine without the presets.
93
+
94
+ ```
95
+ contrib_gitignore_engine # the matching logic
96
+ contrib_gitignore_preset # one opinionated list of paths
97
+ ```
98
+
99
+ A consumer who wants their own path list takes the engine and writes their
100
+ own preset. A consumer who wants the shipped defaults takes both. If the
101
+ engine and the preset were one module, every consumer would be forced to
102
+ either accept the opinionated list or fork the whole thing.
103
+
104
+ ### 2. Avoid grab-bag modules
105
+
106
+ A module's dependencies and `shells=` are the union of its parts. Splitting
107
+ one module into several narrow ones lets each part declare only what it
108
+ actually needs.
109
+
110
+ The failure this avoids is concrete: a helper that used `local` was bundled
111
+ into a general-purpose utilities module, and because `local` is not POSIX,
112
+ that one function excluded ksh for **every** function in the module. The
113
+ module's `shells=` list had to be the union, so one non-portable helper
114
+ cost the whole module its ksh support.
115
+
116
+ Split instead:
117
+
118
+ ```
119
+ contrib_owner_cli_quote # POSIX, no dependencies
120
+ contrib_owner_cli_local # needs a non-POSIX shell
121
+ ```
122
+
123
+ Now the first module keeps `shells=posix` and the second declares
124
+ what it actually needs. The same rule applies to dependencies: a module that
125
+ pulls in a heavy dependency should be separate from one that does not.
126
+
127
+ ### 3. Use owner namespaces
128
+
129
+ Covered above: `contrib_<owner>_<thing>`, one segment per provider, used
130
+ consistently.
131
+
132
+ ### 4. Runtime capability use is allowed
133
+
134
+ A layer module **may** call `sp_cap_*` helpers at run time. A compiled plan
135
+ sources the capability prelude and leaves it in place, so a function the
136
+ module defines can call `sp_cap_os`, `sp_cap_cpu_count`, or any other helper
137
+ long after the profile finished loading.
138
+
139
+ Prefer the `sp_cap_*` helpers over open-coding platform-specific commands.
140
+ See [contrib-modules.md](contrib-modules.md) for the list.
141
+
27
142
  ## Index of engine-shipped shared modules
28
143
 
29
144
  | Module | Version | Exports | Source | Status |
30
145
  |---|---|---|---|---|
31
- | `contrib_path` | 1.0.0 | `contrib_path_prepend`, `contrib_path_append` | `modules/system/contrib_path.sh` | active |
32
- | `contrib_editor` | 1.0.0 | `contrib_editor_defaults` | `modules/system/contrib_editor.sh` | active |
33
- | `contrib_pager` | 1.0.0 | `contrib_pager_defaults` | `modules/system/contrib_pager.sh` | active |
34
- | `contrib_xdg` | 1.0.0 | `contrib_xdg_defaults` | `modules/system/contrib_xdg.sh` | active |
35
- | `contrib_history` | 1.0.0 | `contrib_history_defaults` | `modules/system/contrib_history.sh` | active |
146
+ | `valise_path` | 1.0.0 | `valise_path_prepend`, `valise_path_append` | `modules/system/valise_path.sh` | active |
147
+ | `valise_editor` | 1.0.0 | `valise_editor_defaults` | `modules/system/valise_editor.sh` | active |
148
+ | `valise_pager` | 1.0.0 | `valise_pager_defaults` | `modules/system/valise_pager.sh` | active |
149
+ | `valise_xdg` | 1.0.0 | `valise_xdg_defaults` | `modules/system/valise_xdg.sh` | active |
150
+ | `valise_history` | 1.0.0 | `valise_history_defaults` | `modules/system/valise_history.sh` | active |
151
+ | `valise_platform_posix` | — | `sp_platform_*` helpers | `modules/platform/posix.sh` | active |
152
+ | `valise_platform_macos` | — | `sp_platform_macos_*` helpers | `modules/platform/macos/capabilities.sh` | active |
153
+ | `valise_platform_linux` | — | `sp_platform_linux_*` helpers | `modules/platform/linux/capabilities.sh` | active |
154
+ | `valise_platform_bsd` | — | `sp_platform_bsd_*` helpers | `modules/platform/bsd/capabilities.sh` | active |
36
155
 
37
156
  The example provider tree in this repository
38
157
  (`examples/shared/`) additionally ships:
@@ -42,6 +161,8 @@ The example provider tree in this repository
42
161
  | `contrib_shared_paths` | 1.0.0 | `contrib_shared_paths_setup` | `examples/shared/modules/shared/contrib_shared_paths.sh` | active |
43
162
  | `contrib_shared_umask` | 1.0.0 | `contrib_shared_umask_secure` | `examples/shared/modules/shared/contrib_shared_umask.sh` | active |
44
163
 
164
+ The example provider's owner segment is `shared`.
165
+
45
166
  Update the index in the same change that adds, renames, deprecates, or
46
167
  removes a shared module. Provider repositories should maintain a corresponding
47
168
  index for their own layer modules.
@@ -53,33 +174,35 @@ Every change to a shared module passes the same floor:
53
174
  1. The engine gate: `make check-fast` during iteration and
54
175
  `make VALISE_REQUIRE_TOOLING=1 check` before a release claim (strict
55
176
  tooling is automatic when CI sets `CI=true` or `GITHUB_ACTIONS=true`).
177
+ These targets live in the source repository; the npm package ships the
178
+ runtime, the docs, and the examples, not the Makefile.
56
179
  2. The authoring checklist in
57
180
  [contrib-modules.md](contrib-modules.md): metadata validates, the
58
181
  module loads strict from a clean environment, behavior is idempotent
59
182
  and quiet.
60
183
  3. For engine modules, review happens in this repository's normal commit
61
184
  review. For provider modules, review happens in the provider
62
- repository; the consumer re-applies judgment at re-pin time by
63
- reviewing the vendored diff (see the update policy in
64
- [module-abi.md](module-abi.md)).
185
+ repository, and the consumer reviews the vendored diff again when
186
+ copying a new revision into `layers/<provider>/` (see
187
+ [module-abi.md](module-abi.md#layers)).
65
188
 
66
189
  Breaking changes to behavior require a `version=` bump so the skew rule
67
190
  can catch mixed-version compositions.
68
191
 
69
192
  ## Deprecation
70
193
 
71
- A deprecated module keeps shipping unchanged — its bytes stay available
72
- to every consumer that already pinned them — but is marked for eventual
194
+ A deprecated module keeps shipping unchanged, so its bytes stay available
195
+ to every consumer that already pinned them, but it is marked for eventual
73
196
  removal:
74
197
 
75
198
  1. Set the module's status to `deprecated` in this index.
76
199
  2. Freeze its `version=`: no feature work lands; fixes that cannot wait
77
- follow the normal re-pin policy with the deprecation still visible.
200
+ follow the normal update policy with the deprecation still visible.
78
201
  3. State the replacement (another module, or none) in the index row.
79
202
 
80
203
  A module stays deprecated for at least one release before it may be
81
- removed, so consumers see the deprecation in a re-pin before the
82
- disappearance. The loader continues to load a deprecated module;
204
+ removed, so consumers see the deprecation in an update before the
205
+ disappearance. Builds continue to include a deprecated module;
83
206
  deprecation is a signal to consumers, not a gate.
84
207
 
85
208
  ## Removal
@@ -92,6 +215,6 @@ Removing a shared module is a release-visible change:
92
215
  3. Rebuild the manifest and install: the content-derived release ID
93
216
  changes, making the switch to a post-removal release an explicit,
94
217
  reviewed act.
95
- 4. Consumers keep working on their already-installed sealed releases —
96
- each verifies against its own manifest — and notice the removal at
97
- their next re-pin, when the module is absent from the diff.
218
+ 4. Consumers keep working on their already-installed sealed releases,
219
+ each of which verifies against its own manifest, and notice the removal at
220
+ their next update, when the module is absent from the diff.
@@ -2,13 +2,26 @@
2
2
 
3
3
  - `local/` is the smallest example: one metadata file and one POSIX shell
4
4
  module. It demonstrates sourcing a module without installing a release.
5
- - `e2e/` is a sample consumer profile. Its twelve modules cover dependency
6
- resolution, platform and shell selection, exports, optional dependencies,
7
- release installation, and shared-module composition.
5
+ - `profile-project/` is a small complete project: two modules, a provider
6
+ layer, a bundle, and two variants. It is the shortest path from a clone to
7
+ a loaded profile.
8
+ - `e2e/` is the project `tests/e2e.test.sh` builds. Its thirteen modules
9
+ cover dependency resolution, platform and shell selection, exports,
10
+ optional dependencies, a Fish module, and composition with a layer.
11
+ - `shared/` is a sample provider whose modules a project vendors as a layer.
12
+
13
+ ## Complete project
14
+
15
+ `profile-project/` is the one to read if you want to see what a profile
16
+ project looks like end to end. Its
17
+ [README](profile-project/README.md) walks from a fresh checkout through
18
+ `valise build` and `valise apply` to a `greet` function that works in a new
19
+ login shell.
8
20
 
9
21
  ## Minimal module
10
22
 
11
- From the repository root, load the example with:
23
+ `local/` loads through the development loader, without a project or a
24
+ release. From the repository root:
12
25
 
13
26
  ```sh
14
27
  VALISE_MODULE_ROOT="$PWD/examples/local" \
@@ -27,7 +40,6 @@ The metadata is in `examples/local/module.d/hello_valise.meta`; the body is
27
40
 
28
41
  ## Sample consumer profile
29
42
 
30
- `e2e/README.md` describes how to build its release manifest, install and
31
- verify the release, load its modules, and compose the `examples/shared/`
32
- provider. The example installer writes shell integration under `HOME`, so
33
- use a temporary home if you do not want to change your normal startup files.
43
+ [e2e/README.md](e2e/README.md) builds, installs, and verifies that project
44
+ in a temporary home, loads it in each shell, and composes the `shared/`
45
+ provider as a layer.