Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Never write inline `apt-get`/`apk`/`sudo` branching. Install system packages wit

### Source only `zz-*` scripts

A managed script (anything installed or run through `zz-use`/`zz-setup`) sources nothing but `zz-*` scripts: `. zz-colors`. Shared logic never travels through `.`, because a sourced file shares the caller's shell (variables, `set -e`, traps, `$0`) and breaks the moment the two drift apart. Put it in a command on `PATH` and call it (`vps-network public-ip`, `zz-persist -r KEY`), with its own `zz-use` line and arguments. Two things may still be sourced: a data file in shell syntax that is not a script of the repo (`/etc/os-release`, a settings file the user provides, read under a comment saying so), and a `config.functions` step, which `zz-setup` sources (see below).
A managed script (anything installed or run through `zz-use`/`zz-setup`) sources nothing but `zz-*` scripts: `. zz-colors`. Shared logic never travels through `.`, because a sourced file shares the caller's shell (variables, `set -e`, traps, `$0`) and breaks the moment the two drift apart. Put it in a command on `PATH` and call it (`vps-network public-ip`, `zz-persist -r KEY`), with its own `zz-use` line and arguments. One thing may still be sourced: a data file in shell syntax that is not a script of the repo (`/etc/os-release`, a settings file the user provides, read under a comment saying so).

### Logging

Expand Down Expand Up @@ -88,7 +88,7 @@ Write `#!/bin/sh` scripts that run under dash and busybox. No bashisms:
A repository run by `zz-setup <org>/<repo>` is a set of workspaces, one folder per step. A step's `run.sh` follows the rules above and also these:

- **Runnable step**: the folder holds `package.json` and `run.sh`. `package.json` declares `bin: {"<folder>": "run.sh"}` and `engines: {"zz-setup": "*"}`; without `engines.zz-setup` the folder is a library, never proposed as a step. The folder is a root `workspaces` entry. Order comes from `config.order`, never from the folder name.
- **Actions**: set `config.functions: true` and define `up()`, `down()` and `summary()` (plus any extra action, called with `zz-setup <repo> -o <step> -a <action>`); `zz-setup` sources the bin from its own directory and calls the one asked, so the file has no dispatch code and is not run on its own (`zz-setup ./ -o <step>` runs a local checkout). `config.summary: true` makes `zz-setup` print the step's `summary()` after a run. Without `config.functions` the bin is run with `up` or `down` as its first argument. `up` and `down` are idempotent: a re-run repairs, never fails on what already exists. `down` undoes only what `up` created. `zz-setup` runs `down` steps in reverse order, then `up` steps in order.
- **Actions**: the bin is run with `up` or `down` as its first argument (`zz-setup <repo> -o <step> -a <action>` passes any other); a `config.summary: true` step also answers `summary`, printed after a run. `up` and `down` are idempotent: a re-run repairs, never fails on what already exists. `down` undoes only what `up` created. `zz-setup` runs `down` steps in reverse order, then `up` steps in order.
- **Inputs**: declare every variable in `config.inputs` (`description`, `required`, `default`, `secret`). Read it from the environment; `zz-setup` resolves environment, then env file, then default. A step never prompts: it runs without a terminal and `sudo` drops the environment. Document each input in the step README.
- **Secrets**: generate once, then reuse. Store with `zz-persist -s` (owner-only env file), never echo to a log line other than the final summary, and mark the input `"secret": true`.
- **Dependencies**: list other steps in `dependencies` or `peerDependencies`; `zz-setup` enables them. Steps that cannot share a host name each other in `config.conflicts`. Shared logic lives in scripts that are called, never sourced (see "Source only `zz-*` scripts"): a folder with a `bin` and no `engines.zz-setup` is a script, not a step, and a step reaches it by path (`$(dirname "$0")/../<script>/run.sh`).
Expand Down
Loading