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.
- package/CHANGELOG.md +320 -9
- package/README.md +104 -127
- package/bin/valise +67 -3266
- package/docs/architecture.md +76 -51
- package/docs/contrib-modules.md +180 -173
- package/docs/installation.md +210 -69
- package/docs/module-abi.md +211 -148
- package/docs/projects.md +249 -0
- package/docs/release-policy.md +90 -11
- package/docs/shared-modules.md +149 -26
- package/examples/README.md +20 -8
- package/examples/e2e/README.md +61 -68
- package/examples/e2e/bundles.tsv +6 -0
- package/examples/e2e/module.d/e2e_aliases.meta +1 -2
- package/examples/e2e/module.d/e2e_completions_bash.meta +0 -1
- package/examples/e2e/module.d/e2e_completions_zsh.meta +0 -1
- package/examples/e2e/module.d/e2e_env_setup.meta +2 -3
- package/examples/e2e/module.d/e2e_fish_features.meta +0 -1
- package/examples/e2e/module.d/e2e_generated_config.meta +1 -2
- package/examples/e2e/module.d/e2e_ksh_features.meta +0 -1
- package/examples/e2e/module.d/e2e_layer_probe.meta +1 -2
- package/examples/e2e/module.d/e2e_optional_network.meta +1 -2
- package/examples/e2e/module.d/e2e_platform_tools.meta +8 -0
- package/examples/e2e/module.d/e2e_platform_tools_bsd.meta +2 -3
- package/examples/e2e/module.d/e2e_platform_tools_darwin.meta +2 -3
- package/examples/e2e/module.d/e2e_platform_tools_linux.meta +2 -3
- package/examples/e2e/valise.conf +4 -0
- package/examples/e2e/variants.tsv +3 -0
- package/examples/local/module.d/hello_valise.meta +1 -2
- package/examples/profile-project/README.md +151 -0
- package/examples/profile-project/bundles.tsv +8 -0
- package/examples/profile-project/layers/demo/module.d/contrib_demo_greeting.meta +9 -0
- package/examples/profile-project/layers/demo/modules/shared/contrib_demo_greeting.sh +4 -0
- package/examples/profile-project/module.d/greeting.meta +9 -0
- package/examples/profile-project/module.d/profile_main.meta +8 -0
- package/examples/profile-project/modules/greeting.sh +5 -0
- package/examples/profile-project/valise.conf +4 -0
- package/examples/profile-project/variants.tsv +3 -0
- package/examples/shared/README.md +13 -34
- package/examples/shared/module.d/contrib_shared_paths.meta +2 -3
- package/examples/shared/module.d/contrib_shared_umask.meta +1 -2
- package/examples/shared/modules/shared/contrib_shared_paths.sh +2 -2
- package/lib/capabilities.sh +40 -13
- package/lib/cli/commands.sh +278 -0
- package/lib/cli/common.sh +326 -0
- package/lib/cli/devtools.sh +539 -0
- package/lib/cli/fish-hook.sh +986 -0
- package/lib/cli/integration.sh +337 -0
- package/lib/cli/lifecycle.sh +578 -0
- package/lib/cli/project.sh +1807 -0
- package/lib/cli/store.sh +1023 -0
- package/lib/cli/usage.sh +308 -0
- package/lib/compiler.awk +352 -24
- package/lib/fish/loader.fish +163 -28
- package/lib/fish/metadata.fish +62 -19
- package/lib/fish/profile.fish +170 -0
- package/lib/loader.sh +736 -158
- package/lib/metadata.sh +137 -55
- package/manifests/parser-support.tsv +2 -2
- package/module.d/valise_editor.meta +9 -0
- package/module.d/valise_history.meta +9 -0
- package/module.d/valise_pager.meta +9 -0
- package/module.d/valise_path.meta +9 -0
- package/module.d/{platform_bsd.meta → valise_platform_bsd.meta} +3 -4
- package/module.d/{platform_linux.meta → valise_platform_linux.meta} +3 -4
- package/module.d/{platform_macos.meta → valise_platform_macos.meta} +3 -4
- package/module.d/{platform_posix.meta → valise_platform_posix.meta} +2 -3
- package/module.d/valise_xdg.meta +9 -0
- package/modules/system/{contrib_editor.sh → valise_editor.sh} +2 -2
- package/modules/system/{contrib_history.sh → valise_history.sh} +2 -2
- package/modules/system/{contrib_pager.sh → valise_pager.sh} +2 -2
- package/modules/system/{contrib_path.sh → valise_path.sh} +3 -3
- package/modules/system/{contrib_xdg.sh → valise_xdg.sh} +2 -2
- package/package.json +91 -9
- package/docs/variants.md +0 -63
- package/entrypoints/.gitkeep +0 -0
- package/entrypoints/fish/profile.fish +0 -99
- package/examples/e2e/build-manifest.sh +0 -250
- package/examples/local/.gitkeep +0 -0
- package/lib/.gitkeep +0 -0
- package/manifests/.gitkeep +0 -0
- package/module.d/.gitkeep +0 -0
- package/module.d/contrib_editor.meta +0 -10
- package/module.d/contrib_history.meta +0 -10
- package/module.d/contrib_pager.meta +0 -10
- package/module.d/contrib_path.meta +0 -10
- package/module.d/contrib_xdg.meta +0 -10
- package/modules/.gitkeep +0 -0
package/docs/projects.md
ADDED
|
@@ -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).
|
package/docs/release-policy.md
CHANGED
|
@@ -2,9 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
## Current status
|
|
4
4
|
|
|
5
|
-
`valise-sh` is at **0.
|
|
6
|
-
format do not have a backward-compatibility guarantee.
|
|
7
|
-
|
|
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
|
|
23
|
-
|
|
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`
|
|
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
|
|
37
|
-
|
|
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.
|
package/docs/shared-modules.md
CHANGED
|
@@ -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,
|
|
5
|
-
and how modules are indexed, deprecated, and
|
|
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
|
-
|
|
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
|
|
13
|
-
|
|
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
|
-
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
| `
|
|
32
|
-
| `
|
|
33
|
-
| `
|
|
34
|
-
| `
|
|
35
|
-
| `
|
|
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
|
|
63
|
-
|
|
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
|
|
72
|
-
to every consumer that already pinned them
|
|
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
|
|
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
|
|
82
|
-
disappearance.
|
|
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
|
|
97
|
-
their next
|
|
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.
|
package/examples/README.md
CHANGED
|
@@ -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
|
-
- `
|
|
6
|
-
|
|
7
|
-
|
|
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
|
-
|
|
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
|
-
|
|
31
|
-
|
|
32
|
-
provider
|
|
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.
|