@mark1russell7/stack-setup 0.0.0-bootstrap.0 → 0.1.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/LICENSE +21 -0
- package/README.md +154 -1
- package/build/add-on.d.ts +12 -0
- package/build/add-on.d.ts.map +1 -0
- package/build/add-on.js +23 -0
- package/build/add-on.js.map +1 -0
- package/build/index.d.ts +148 -0
- package/build/index.d.ts.map +1 -0
- package/build/index.js +507 -0
- package/build/index.js.map +1 -0
- package/build/join-DS3ZZ5hb.js +447 -0
- package/build/join-DS3ZZ5hb.js.map +1 -0
- package/build/layer-DWfBSz3H.js +58 -0
- package/build/layer-DWfBSz3H.js.map +1 -0
- package/build/layer-Db50psxJ.d.ts +151 -0
- package/build/layer-Db50psxJ.d.ts.map +1 -0
- package/build/schema.d.ts +21 -0
- package/build/schema.d.ts.map +1 -0
- package/build/schema.js +117 -0
- package/build/schema.js.map +1 -0
- package/package.json +71 -6
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mark Russell
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,156 @@
|
|
|
1
1
|
# @mark1russell7/stack-setup
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The setup inside a host, from the records of a system stack. The package has typed steps, their order from the needs, a gate and a generator of a shell script.
|
|
4
|
+
|
|
5
|
+
It is the setup add-on of [`@mark1russell7/system-stack`](../system-stack/README.md). The core knows only parts and needs. This package tells how a host gets its packages, users, files, programs, swap and services.
|
|
6
|
+
|
|
7
|
+
Nobody writes the script by hand. The script is a result of a query over the records, so it changes when the stack changes.
|
|
8
|
+
|
|
9
|
+
Each function is a plain function with no clock, no network and no file. Only the script makes changes, on the host that starts it.
|
|
10
|
+
|
|
11
|
+
## The rule
|
|
12
|
+
|
|
13
|
+
Each step checks before it changes. A step whose check passes changes nothing. Thus a second run of the script shows no change.
|
|
14
|
+
|
|
15
|
+
After a change, the check of the step must pass. If it does not pass, the script stops with a fault. The fault gives the number of the condition that fails, and no value.
|
|
16
|
+
|
|
17
|
+
The script holds no secret. A text reads a variable with `{ $var: "NAME" }`, and the script reads the value from its environment.
|
|
18
|
+
|
|
19
|
+
The generator starts with the gate. A layer with an error gives no script.
|
|
20
|
+
|
|
21
|
+
## The entries
|
|
22
|
+
|
|
23
|
+
| Entry | What it has |
|
|
24
|
+
| --- | --- |
|
|
25
|
+
| `@mark1russell7/stack-setup` | The records of a layer, the order of the profiles, the gate, the generator of the script and a sample. |
|
|
26
|
+
| `@mark1russell7/stack-setup/schema` | `setupSchema`, the zod schema of a layer, with `parseSetup`. |
|
|
27
|
+
| `@mark1russell7/stack-setup/add-on` | `setupAddOn`, the add-on in the form of the layer contract of the core. |
|
|
28
|
+
|
|
29
|
+
The root entry has no schema library. Thus a page that only shows a script gets no zod.
|
|
30
|
+
|
|
31
|
+
## Install
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
npm install @mark1russell7/stack-setup @mark1russell7/system-stack
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## A layer
|
|
38
|
+
|
|
39
|
+
A setup layer has variables and profiles. Its format has the name `setup/1`. A stack keeps it in `Stack.layers`, with the key `setup/1`.
|
|
40
|
+
|
|
41
|
+
A profile sets up one part of the stack on one or more hosts. It has a list of steps.
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
import type { SetupLayer } from "@mark1russell7/stack-setup";
|
|
45
|
+
|
|
46
|
+
const layer: SetupLayer = {
|
|
47
|
+
schema: "setup/1",
|
|
48
|
+
variables: [{ name: "APP_TOKEN", sensitive: true, description: "The token of the program" }],
|
|
49
|
+
profiles: [
|
|
50
|
+
{
|
|
51
|
+
name: "app",
|
|
52
|
+
part: "app",
|
|
53
|
+
hosts: ["host-a"],
|
|
54
|
+
steps: [
|
|
55
|
+
{ kind: "user", id: "user", name: "app", shell: "/usr/sbin/nologin" },
|
|
56
|
+
{ kind: "file", id: "env", path: "/etc/app/env", text: ["APP_TOKEN=", { $var: "APP_TOKEN" }, "\n"], mode: "600" },
|
|
57
|
+
],
|
|
58
|
+
},
|
|
59
|
+
],
|
|
60
|
+
};
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## The steps
|
|
64
|
+
|
|
65
|
+
| Kind | The change | The check |
|
|
66
|
+
| --- | --- | --- |
|
|
67
|
+
| `package` | It installs the packages with `apt-get`. | Each package is installed. |
|
|
68
|
+
| `user` | It makes a user with a home folder. It sets the login shell, the groups and the SSH keys. | The user has the shell, each group and the keys. |
|
|
69
|
+
| `file` | It writes a file with its text, its mode, its owner and its group. | The file has the text, the mode, the owner and the group. |
|
|
70
|
+
| `download` | It downloads a file over HTTPS, and it compares the SHA-256. | The file has the SHA-256 and the mode. |
|
|
71
|
+
| `swap` | It makes a swap file of a size in MiB. It turns it on and adds it to `/etc/fstab`. | The file has the size, the swap is on, and `/etc/fstab` has it. |
|
|
72
|
+
| `service` | It writes the unit of a `systemd` service, and it enables and starts the service. | The unit has the text, and the service is enabled and active. |
|
|
73
|
+
| `command` | It starts a program with its arguments, as root or as a user. | Its own check command passes. |
|
|
74
|
+
|
|
75
|
+
A `command` step starts its program through `env` or `runuser`. Thus no function or builtin of the shell is the program.
|
|
76
|
+
|
|
77
|
+
## The order
|
|
78
|
+
|
|
79
|
+
`profileOrder` gives the profiles of a host in the order of the needs. A profile comes after each profile of the host whose part its part needs.
|
|
80
|
+
|
|
81
|
+
Two profiles whose parts need each other make a cycle. The gate gives the fault `setup-cycle` for it.
|
|
82
|
+
|
|
83
|
+
## The gate
|
|
84
|
+
|
|
85
|
+
`checkSetup` gives each fault of a layer for a stack. A list with no error tells that the gate passes.
|
|
86
|
+
|
|
87
|
+
| Code | Level | The fault |
|
|
88
|
+
| --- | --- | --- |
|
|
89
|
+
| `setup-name` | error | A name does not have its form: the name of a profile, a variable, a user, a group, a service or a package, or the `id` of a step. |
|
|
90
|
+
| `setup-variable-twice` | error | The layer has two variables with one name. |
|
|
91
|
+
| `setup-profile-twice` | error | The layer has two profiles with one name. |
|
|
92
|
+
| `setup-step-twice` | error | A profile has two steps with one `id`. |
|
|
93
|
+
| `setup-part` | error | The part of a profile is not a part of the stack. |
|
|
94
|
+
| `setup-host` | error | A profile names no host, or a host that is not a part of the stack. |
|
|
95
|
+
| `setup-variable` | error | A text reads a variable that the layer does not have. |
|
|
96
|
+
| `setup-secret-exposed` | error | A sensitive variable is in a unit, in a command or in a file that each user can read. |
|
|
97
|
+
| `setup-text` | error | A text has the character NUL, or a key is not one line. |
|
|
98
|
+
| `setup-path` | error | A path is not an absolute path of the safe characters. |
|
|
99
|
+
| `setup-path-twice` | error | Two steps of one host write one path. |
|
|
100
|
+
| `setup-user-twice` | error | Two steps of one host set up one user. |
|
|
101
|
+
| `setup-mode` | error | A mode is not a mode in octal. |
|
|
102
|
+
| `setup-url` | error | An address is not an HTTPS address with a host name. An address with a user or a password is a fault. |
|
|
103
|
+
| `setup-sha256` | error | A SHA-256 is not 64 lowercase hexadecimal digits. |
|
|
104
|
+
| `setup-swap-size` | error | The size of a swap file is not a whole number of MiB from 1 to 65536. |
|
|
105
|
+
| `setup-program` | error | A command is empty, or its first argument is not a literal program. |
|
|
106
|
+
| `setup-cycle` | error | The parts of the profiles of one host need each other. |
|
|
107
|
+
| `setup-variable-unused` | warning | No step reads a variable. |
|
|
108
|
+
| `setup-empty` | warning | A profile has no step, or a package step names no package. |
|
|
109
|
+
|
|
110
|
+
## The script
|
|
111
|
+
|
|
112
|
+
`setupScript` gives the script of one host. The script is POSIX `sh`, and it passes `shellcheck -s sh`. It needs root, `apt-get`, `systemd` and the GNU tools.
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
import { SAMPLE_STACK } from "@mark1russell7/system-stack";
|
|
116
|
+
import { SAMPLE_SETUP, setupScript } from "@mark1russell7/stack-setup";
|
|
117
|
+
|
|
118
|
+
const result = setupScript(SAMPLE_SETUP, SAMPLE_STACK, "cloud-host");
|
|
119
|
+
if (result.ok) console.log(result.script);
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
The first argument of the script is the mode:
|
|
123
|
+
|
|
124
|
+
- `apply` makes each change. It is the default.
|
|
125
|
+
- `check` makes no change. It tells each step that has a change.
|
|
126
|
+
|
|
127
|
+
Give the value of each variable in the environment of the script:
|
|
128
|
+
|
|
129
|
+
```sh
|
|
130
|
+
sudo env APP_TOKEN="$APP_TOKEN" sh setup.sh check
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
| Exit code | The result |
|
|
134
|
+
| --- | --- |
|
|
135
|
+
| 0 | Each step is ok. |
|
|
136
|
+
| 1 | A step failed. |
|
|
137
|
+
| 2 | The mode `check` found a change. |
|
|
138
|
+
| 64 | A usage fault: a mode that is not known, a start that is not root, or a variable with no value. |
|
|
139
|
+
|
|
140
|
+
Each step writes one line: `ok`, `change` or `changed`, and the address of the step. The last line gives the count of the changes.
|
|
141
|
+
|
|
142
|
+
## The test on a host
|
|
143
|
+
|
|
144
|
+
A unit test cannot tell if a shell operates the script correctly. The test `e2e/setup.e2e.ts` starts a script on a CI runner, which is a new machine for each job.
|
|
145
|
+
|
|
146
|
+
The test examines `shellcheck` and the exit codes. It examines a first start with changes, and a second start with no change. It also examines the records on the host and the repair of a changed file.
|
|
147
|
+
|
|
148
|
+
```sh
|
|
149
|
+
pnpm --filter @mark1russell7/stack-setup run test:setup
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
The test needs root through `sudo`. Start it only on a machine that you can discard.
|
|
153
|
+
|
|
154
|
+
## License
|
|
155
|
+
|
|
156
|
+
MIT
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { l as SetupLayer } from "./layer-Db50psxJ.js";
|
|
2
|
+
import { StackJoiner } from "@mark1russell7/system-stack";
|
|
3
|
+
/**
|
|
4
|
+
* This function gives the setup add-on.
|
|
5
|
+
*
|
|
6
|
+
* - `schema` is `setup/1`, the key of the layer in `Stack.layers`.
|
|
7
|
+
* - `parse` is `parseSetup`.
|
|
8
|
+
* - `check` is the gate `checkSetup`.
|
|
9
|
+
* - `join` is `joinSetup`. It joins the setup layers of the fragments of a stack.
|
|
10
|
+
*/
|
|
11
|
+
export declare function setupAddOn(): StackJoiner<SetupLayer>;
|
|
12
|
+
//# sourceMappingURL=add-on.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"add-on.d.ts","names":[],"sources":["../src/add-on.ts"],"mappings":";;;;;;;;;;wBAiBgB,cAAc,YAAY"}
|
package/build/add-on.js
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { r as checkSetup, t as joinSetup } from "./join-DS3ZZ5hb.js";
|
|
2
|
+
import { t as SETUP_SCHEMA } from "./layer-DWfBSz3H.js";
|
|
3
|
+
import { parseSetup } from "./schema.js";
|
|
4
|
+
// src/add-on.ts
|
|
5
|
+
/**
|
|
6
|
+
* This function gives the setup add-on.
|
|
7
|
+
*
|
|
8
|
+
* - `schema` is `setup/1`, the key of the layer in `Stack.layers`.
|
|
9
|
+
* - `parse` is `parseSetup`.
|
|
10
|
+
* - `check` is the gate `checkSetup`.
|
|
11
|
+
* - `join` is `joinSetup`. It joins the setup layers of the fragments of a stack.
|
|
12
|
+
*/
|
|
13
|
+
function setupAddOn() {
|
|
14
|
+
return {
|
|
15
|
+
schema: SETUP_SCHEMA,
|
|
16
|
+
parse: parseSetup,
|
|
17
|
+
check: checkSetup,
|
|
18
|
+
join: joinSetup
|
|
19
|
+
};
|
|
20
|
+
}
|
|
21
|
+
export { setupAddOn };
|
|
22
|
+
|
|
23
|
+
//# sourceMappingURL=add-on.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"add-on.js","names":[],"sources":["../src/add-on.ts"],"sourcesContent":["import type { StackJoiner } from \"@mark1russell7/system-stack\";\nimport { checkSetup } from \"./check.ts\";\nimport { joinSetup } from \"./join.ts\";\nimport { SETUP_SCHEMA, type SetupLayer } from \"./layer.ts\";\nimport { parseSetup } from \"./schema.ts\";\n\n// The setup add-on in the form of the layer contract. A host gives it to `checkStackLayers` and to `joinStacks` of the core.\n// This entry has the schema library, so the root entry does not import it.\n\n/**\n * This function gives the setup add-on.\n *\n * - `schema` is `setup/1`, the key of the layer in `Stack.layers`.\n * - `parse` is `parseSetup`.\n * - `check` is the gate `checkSetup`.\n * - `join` is `joinSetup`. It joins the setup layers of the fragments of a stack.\n */\nexport function setupAddOn(): StackJoiner<SetupLayer> {\n return { schema: SETUP_SCHEMA, parse: parseSetup, check: checkSetup, join: joinSetup };\n}\n"],"mappings":";;;;;;;;;;;;AAiBA,SAAgB,aAAsC;CACpD,OAAO;EAAE,QAAQ;EAAc,OAAO;EAAY,OAAO;EAAY,MAAM;CAAU;AACvF"}
|
package/build/index.d.ts
ADDED
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
import { C as unitPath, S as textVariables, _ as isVariableRead, a as Profile, b as stepTexts, c as ServiceStep, d as Step, f as StepKind, g as VariableRead, h as Variable, i as PackageStep, l as SetupLayer, m as UserStep, n as DownloadStep, o as SETUP_SCHEMA, p as SwapStep, r as FileStep, s as STEP_KINDS, t as CommandStep, u as SetupText, v as stepAddress, x as textParts, y as stepPaths } from "./layer-Db50psxJ.js";
|
|
2
|
+
import { Fault, LayerParse, LayerPiece, Stack } from "@mark1russell7/system-stack";
|
|
3
|
+
/** The order of the profiles of one host. */
|
|
4
|
+
export interface ProfileOrder {
|
|
5
|
+
/** The profiles of the host in the order of the setup. It is empty when the needs have a cycle. */
|
|
6
|
+
readonly profiles: readonly Profile[];
|
|
7
|
+
/** The names of the profiles in each cycle of the needs. Each cycle has two or more profiles. */
|
|
8
|
+
readonly cycles: readonly (readonly string[])[];
|
|
9
|
+
}
|
|
10
|
+
/** This function gives each host of a layer once, in the order of its first profile. */
|
|
11
|
+
export declare function setupHosts(layer: SetupLayer): string[];
|
|
12
|
+
/** This function gives the profiles of a layer that name a host, in the layer order. */
|
|
13
|
+
export declare function hostProfiles(layer: SetupLayer, host: string): Profile[];
|
|
14
|
+
/**
|
|
15
|
+
* This function gives, for each profile of a list, the positions of the profiles of the list that come before it.
|
|
16
|
+
* A profile comes after each other profile whose part is a needed part of its part. Two profiles of one part have no order.
|
|
17
|
+
*
|
|
18
|
+
* @param profiles - The profiles of one host.
|
|
19
|
+
* @param stack - The stack. `neededParts` of the core gives the needs.
|
|
20
|
+
* @returns For each position of the list, the positions that come before it.
|
|
21
|
+
*/
|
|
22
|
+
export declare function profilesBefore(profiles: readonly Profile[], stack: Stack): number[][];
|
|
23
|
+
/**
|
|
24
|
+
* This function gives the profiles of a host in the order of the setup.
|
|
25
|
+
*
|
|
26
|
+
* - A profile comes after each profile of the host whose part its part needs.
|
|
27
|
+
* - Where the needs give no order, the layer order holds. Thus the order is stable.
|
|
28
|
+
* - When the needs of two or more profiles make a cycle, the result has no order and names each cycle.
|
|
29
|
+
*
|
|
30
|
+
* `stronglyConnectedComponents` of `@mark1russell7/collections/graph` finds the cycles.
|
|
31
|
+
*
|
|
32
|
+
* @param layer - The setup layer.
|
|
33
|
+
* @param stack - The stack.
|
|
34
|
+
* @param host - The `id` of the host.
|
|
35
|
+
* @returns The order, or the cycles.
|
|
36
|
+
*/
|
|
37
|
+
export declare function profileOrder(layer: SetupLayer, stack: Stack, host: string): ProfileOrder;
|
|
38
|
+
/** These are the codes of the faults of a setup layer. */
|
|
39
|
+
export declare const SETUP_CODES: readonly ["setup-name", "setup-variable-twice", "setup-profile-twice", "setup-step-twice", "setup-part", "setup-host", "setup-variable", "setup-variable-unused", "setup-secret-exposed", "setup-text", "setup-path", "setup-path-twice", "setup-user-twice", "setup-mode", "setup-url", "setup-sha256", "setup-swap-size", "setup-program", "setup-empty", "setup-cycle"];
|
|
40
|
+
/** A code of a fault of a setup layer. */
|
|
41
|
+
export type SetupCode = (typeof SETUP_CODES)[number];
|
|
42
|
+
/**
|
|
43
|
+
* A fault of a setup layer. Its field `at` is the place of the fault.
|
|
44
|
+
*
|
|
45
|
+
* - For a step, `at` is the address of the step: the name of its profile, a point and its `id`.
|
|
46
|
+
* - For a profile, `at` is the name of the profile.
|
|
47
|
+
* - For a variable, `at` is `var.` and its name.
|
|
48
|
+
* - For a host with no profile, `at` is the `id` of the host.
|
|
49
|
+
*/
|
|
50
|
+
export interface SetupFault extends Fault {
|
|
51
|
+
readonly code: SetupCode;
|
|
52
|
+
/** The `id` of the host, for a fault of the steps of one host. */
|
|
53
|
+
readonly host?: string | undefined;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* This function gives each fault of a setup layer for a stack. A list with no error tells that the gate passes.
|
|
57
|
+
*
|
|
58
|
+
* The errors:
|
|
59
|
+
* - `setup-name`: the name of a profile, a variable, a user, a group, a service or a package does not have its form. Or the `id` of a step does not have its form.
|
|
60
|
+
* - `setup-variable-twice`, `setup-profile-twice`, `setup-step-twice`: two records have one name.
|
|
61
|
+
* - `setup-part`: the part of a profile is not a part of the stack.
|
|
62
|
+
* - `setup-host`: a profile names no host, or a host that is not a part of the stack.
|
|
63
|
+
* - `setup-variable`: a text reads a variable that the layer does not have.
|
|
64
|
+
* - `setup-secret-exposed`: a sensitive variable is in a unit, in a command, or in a file that each user can read.
|
|
65
|
+
* - `setup-text`: a text has the character NUL, or a key is not one line.
|
|
66
|
+
* - `setup-path`: a path is not an absolute path of the safe characters.
|
|
67
|
+
* - `setup-path-twice`: two steps of one host write one path.
|
|
68
|
+
* - `setup-user-twice`: two steps of one host set up one user.
|
|
69
|
+
* - `setup-mode`, `setup-url`, `setup-sha256`, `setup-swap-size`: a mode, an address, a SHA-256 or a size does not have its form.
|
|
70
|
+
* - `setup-program`: a command is empty, or its first argument is not a literal program.
|
|
71
|
+
* - `setup-cycle`: the needs of the parts of the profiles of one host make a cycle.
|
|
72
|
+
*
|
|
73
|
+
* The warnings:
|
|
74
|
+
* - `setup-variable-unused`: no step reads a variable.
|
|
75
|
+
* - `setup-empty`: a profile has no step, or a package step names no package.
|
|
76
|
+
*
|
|
77
|
+
* @param layer - The setup layer.
|
|
78
|
+
* @param stack - The stack. Its parts and their needs give the hosts and the order.
|
|
79
|
+
* @returns The faults.
|
|
80
|
+
*/
|
|
81
|
+
export declare function checkSetup(layer: SetupLayer, stack: Stack): SetupFault[];
|
|
82
|
+
/** This function tells if a list of faults has an error. */
|
|
83
|
+
export declare function hasSetupError(faults: readonly SetupFault[]): boolean;
|
|
84
|
+
/**
|
|
85
|
+
* This function joins the setup layers of the fragments of a stack into one layer.
|
|
86
|
+
*
|
|
87
|
+
* - The variables and the profiles are in the order of the fragments.
|
|
88
|
+
* - A variable name or a profile name in two or more fragments is a fault, also when the records are equal.
|
|
89
|
+
*
|
|
90
|
+
* A profile of one fragment can read a variable of a different fragment. The joined layer has the field `variables` when a fragment has it.
|
|
91
|
+
* The function is pure, and it changes no layer. The gate `checkSetup` examines the joined layer afterward.
|
|
92
|
+
*
|
|
93
|
+
* @param pieces - The layers, with the name of the fragment of each one, in the order of the fragments.
|
|
94
|
+
* @returns The joined layer, or the faults of the join.
|
|
95
|
+
*/
|
|
96
|
+
export declare function joinSetup(pieces: readonly LayerPiece<SetupLayer>[]): LayerParse<SetupLayer>;
|
|
97
|
+
/** The exit codes of a setup script. */
|
|
98
|
+
export declare const SETUP_EXIT: {
|
|
99
|
+
readonly ok: 0;
|
|
100
|
+
readonly failed: 1;
|
|
101
|
+
readonly changes: 2;
|
|
102
|
+
readonly usage: 64;
|
|
103
|
+
};
|
|
104
|
+
/** The modes of a setup script, its first argument. `apply` is the default. */
|
|
105
|
+
export declare const SETUP_MODES: readonly ["apply", "check"];
|
|
106
|
+
/** The result of the generator: the script, or the faults of the gate. */
|
|
107
|
+
export type SetupScript = {
|
|
108
|
+
readonly ok: true;
|
|
109
|
+
readonly script: string;
|
|
110
|
+
} | {
|
|
111
|
+
readonly ok: false;
|
|
112
|
+
readonly faults: readonly SetupFault[];
|
|
113
|
+
};
|
|
114
|
+
/**
|
|
115
|
+
* This function gives one word of the shell for a text. A literal part is quoted with `escapeShell` of `@mark1russell7/text/shell`.
|
|
116
|
+
* A variable part is `"$NAME"`. Thus the shell expands only the variables of the text.
|
|
117
|
+
*/
|
|
118
|
+
export declare function shellWord(text: SetupText): string;
|
|
119
|
+
/**
|
|
120
|
+
* This function gives the setup script of one host. The gate `checkSetup` comes first: a layer with an error gives no script.
|
|
121
|
+
*
|
|
122
|
+
* The script:
|
|
123
|
+
* - It is POSIX `sh`, and it passes `shellcheck -s sh`. It needs root, `apt`, `systemd` and the GNU tools of Debian or Ubuntu.
|
|
124
|
+
* - Its first argument is the mode. `apply` makes each change. `check` makes no change, and it exits with 2 when a step has a change.
|
|
125
|
+
* - It exits with 64 for a usage fault. A usage fault is a mode that is not known, a start that is not root, or a variable with no value.
|
|
126
|
+
* - Each step starts its check first. Only a step with a failing check makes its change, and then its check must pass.
|
|
127
|
+
* - It reads the value of each variable from its environment. It names the variables of the steps of this host only.
|
|
128
|
+
* - It holds no description of a record. Only names, paths and the texts of the steps are in it.
|
|
129
|
+
*
|
|
130
|
+
* The steps come in the order of `profileOrder`: a profile comes after each profile of the host whose part its part needs.
|
|
131
|
+
*
|
|
132
|
+
* @param layer - The setup layer.
|
|
133
|
+
* @param stack - The stack.
|
|
134
|
+
* @param host - The `id` of the host.
|
|
135
|
+
* @returns The script, or the faults of the gate.
|
|
136
|
+
*/
|
|
137
|
+
export declare function setupScript(layer: SetupLayer, stack: Stack, host: string): SetupScript;
|
|
138
|
+
/**
|
|
139
|
+
* A sample setup layer for `SAMPLE_STACK` of the core. Each name, address and checksum is an example: the file at the address does not exist.
|
|
140
|
+
*
|
|
141
|
+
* - The profile `program` sets up the part `program-cloud` on the host `cloud-host`: the program, its environment file and its service.
|
|
142
|
+
* - The profile `base` sets up the host itself: the packages, a swap file and the user of the program.
|
|
143
|
+
*
|
|
144
|
+
* The layer has `program` first. The part `program-cloud` needs `cloud-host`, so the order of the setup has `base` first.
|
|
145
|
+
*/
|
|
146
|
+
export declare const SAMPLE_SETUP: SetupLayer;
|
|
147
|
+
export { CommandStep, DownloadStep, FileStep, PackageStep, Profile, SETUP_SCHEMA, STEP_KINDS, ServiceStep, SetupLayer, SetupText, Step, StepKind, SwapStep, UserStep, Variable, VariableRead, isVariableRead, stepAddress, stepPaths, stepTexts, textParts, textVariables, unitPath };
|
|
148
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/order.ts","../src/check.ts","../src/join.ts","../src/script.ts","../src/sample.ts"],"mappings":";;;iBAQiB;;WAEN,mBAAmB;;WAEnB;;;wBAIK,WAAW,OAAO;;wBAOlB,aAAa,OAAO,YAAY,eAAe;;;;;;;;;wBAY/C,eAAe,mBAAmB,WAAW,OAAO;;;;;;;;;;;;;;;wBAyBpD,aAAa,OAAO,YAAY,OAAO,OAAO,eAAe;;qBCpChE;;YA6CD,oBAAoB;;;;;;;;;iBAUf,mBAAmB;WACzB,MAAM;;WAEN;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA+MK,WAAW,OAAO,YAAY,OAAO,QAAQ;;wBAyB7C,cAAc,iBAAiB;;;;;;;;;;;;;wBCzS/B,UAAU,iBAAiB,WAAW,gBAAgB,WAAW;;qBCYpE;WAAuB;WAAgB;WAAoB;WAAqB;;;qBAGhF;;YAGD;WAAyB;WAAmB;;WAA8B;WAAoB,iBAAiB;;;;;;wBA+F3G,UAAU,MAAM;;;;;;;;;;;;;;;;;;;wBA8OhB,YAAY,OAAO,YAAY,OAAO,OAAO,eAAe;;;;;;;;;qBCpV/D,cAAc"}
|