heim 0.0.1 → 0.1.0-alpha.2

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/gen/heim.d.ts ADDED
@@ -0,0 +1,266 @@
1
+ /* eslint-disable */
2
+ /**
3
+ * This file was automatically generated by json-schema-to-typescript.
4
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
5
+ * and run json-schema-to-typescript to regenerate this file.
6
+ */
7
+
8
+ /**
9
+ * This json schema defines common types used in the Go CLI and the TypeScript library.
10
+ */
11
+ export interface HeimTypes {
12
+ /**
13
+ * The manifest of the heim app.
14
+ */
15
+ manifest: {
16
+ /**
17
+ * Part of the id of the app. It needs to be unique within one namespace.
18
+ */
19
+ name: string;
20
+ /**
21
+ * The version of the app, must be a valid semver version.
22
+ */
23
+ version: string;
24
+ /**
25
+ * Display name shown in the UI.
26
+ */
27
+ title: LocalizedString | string;
28
+ /**
29
+ * A short description of the app.
30
+ */
31
+ tagline: LocalizedString1 | string;
32
+ /**
33
+ * The description of the app. It needs to be a markdown file.
34
+ */
35
+ readme?: LocalizedString2 | string;
36
+ /**
37
+ * The category of the app.
38
+ */
39
+ category:
40
+ | "books"
41
+ | "medical"
42
+ | "business"
43
+ | "music"
44
+ | "developer-tools"
45
+ | "navigation"
46
+ | "education"
47
+ | "news"
48
+ | "entertainment"
49
+ | "photo-and-video"
50
+ | "finance"
51
+ | "productivity"
52
+ | "food-and-drink"
53
+ | "reference"
54
+ | "games"
55
+ | "graphics-and-design"
56
+ | "shopping"
57
+ | "health-and-fitness"
58
+ | "social-networking"
59
+ | "lifestyle"
60
+ | "sports"
61
+ | "kids"
62
+ | "travel"
63
+ | "magazines-and-newspapers"
64
+ | "utilities"
65
+ | "weather";
66
+ /**
67
+ * The developer (individual person or company) of the app. This is either you or the original developer of the software.
68
+ */
69
+ developer: string;
70
+ /**
71
+ * The icon of the app. It needs to be an SVG file.
72
+ */
73
+ icon?: string;
74
+ /**
75
+ * A list of images that showcase the app.
76
+ */
77
+ galleryImages?: string[] | LocalizedString3;
78
+ /**
79
+ * The website of the app.
80
+ */
81
+ website?: string;
82
+ /**
83
+ * The version control repository of the app (e.g. GitHub).
84
+ */
85
+ repository?: string;
86
+ /**
87
+ * The support website of the app.
88
+ */
89
+ support?: string;
90
+ /**
91
+ * The license file of the app.
92
+ */
93
+ license?: LocalizedString4 | string;
94
+ };
95
+ /**
96
+ * The http(s) configuration of the user interface for the app.
97
+ */
98
+ ui?: {
99
+ /**
100
+ * The name of the compose service that provides the user interface.
101
+ */
102
+ service: string;
103
+ /**
104
+ * The port of the compose service that provides the user interface. Note that this port does NOT need to be exposed by the container runtime.
105
+ */
106
+ port: number;
107
+ /**
108
+ * The url path of the compose service that provides the user interface.
109
+ */
110
+ path?: string;
111
+ /**
112
+ * Whether the user interface of this app has an auth in front of it. Can be 'true' if the app itself provides an authentication mechanism or is intended to be public.
113
+ */
114
+ hasAuth?: boolean;
115
+ };
116
+ /**
117
+ * The backup configuration of the app.
118
+ */
119
+ backup?: {
120
+ volumes?: {
121
+ /**
122
+ * A list of volume names to include in the backup. If neither this list nor the exclude list is set, all volumes will be included. If both lists are set, only the volumes in the include list that are not in the exclude list will be included.
123
+ */
124
+ include?: string[];
125
+ /**
126
+ * A list of volume names to exclude from the backup. If neither this list nor the include list is set, all volumes will be included. If both lists are set, only the volumes in the include list that are not in the exclude list will be included.
127
+ */
128
+ exclude?: string[];
129
+ };
130
+ /**
131
+ * The command to run before backing up the app.
132
+ */
133
+ beforeBackup?: {
134
+ /**
135
+ * The name of the compose service to run the command in.
136
+ */
137
+ service?: string;
138
+ /**
139
+ * The command to run before backing up the app.
140
+ */
141
+ command?: string;
142
+ };
143
+ /**
144
+ * The command to run after backing up the app.
145
+ */
146
+ afterBackup?: {
147
+ /**
148
+ * The name of the compose service to run the command in.
149
+ */
150
+ service?: string;
151
+ /**
152
+ * The command to run after backing up the app.
153
+ */
154
+ command?: string;
155
+ };
156
+ /**
157
+ * The command to run before restoring the app.
158
+ */
159
+ beforeRestore?: {
160
+ /**
161
+ * The name of the compose service to run the command in.
162
+ */
163
+ service?: string;
164
+ /**
165
+ * The command to run before restoring the app.
166
+ */
167
+ command?: string;
168
+ };
169
+ /**
170
+ * The command to run after restoring the app.
171
+ */
172
+ afterRestore?: {
173
+ /**
174
+ * The name of the compose service to run the command in.
175
+ */
176
+ service?: string;
177
+ /**
178
+ * The command to run after restoring the app.
179
+ */
180
+ command?: string;
181
+ };
182
+ };
183
+ /**
184
+ * The hooks configuration of the app.
185
+ */
186
+ hooks?: {
187
+ /**
188
+ * The command to run before installing the app.
189
+ */
190
+ preInstall?: string;
191
+ /**
192
+ * The command to run after installing the app.
193
+ */
194
+ postInstall?: string;
195
+ /**
196
+ * The command to run before updating the app.
197
+ */
198
+ preUpdate?: string;
199
+ /**
200
+ * The command to run after updating the app.
201
+ */
202
+ postUpdate?: string;
203
+ /**
204
+ * The command to run before uninstalling the app.
205
+ */
206
+ preUninstall?: string;
207
+ /**
208
+ * The command to run after uninstalling the app.
209
+ */
210
+ postUninstall?: string;
211
+ /**
212
+ * The command to run before backing up the app.
213
+ */
214
+ preBackup?: string;
215
+ /**
216
+ * The command to run after backing up the app.
217
+ */
218
+ postBackup?: string;
219
+ /**
220
+ * The command to run before restoring the app.
221
+ */
222
+ preRestore?: string;
223
+ /**
224
+ * The command to run after restoring the app.
225
+ */
226
+ postRestore?: string;
227
+ };
228
+ }
229
+ /**
230
+ * A string that is translated in different languages.
231
+ */
232
+ export interface LocalizedString {
233
+ en: string[] | string;
234
+ [k: string]: string;
235
+ }
236
+ /**
237
+ * A string that is translated in different languages.
238
+ */
239
+ export interface LocalizedString1 {
240
+ en: string[] | string;
241
+ [k: string]: string;
242
+ }
243
+ /**
244
+ * A string that is translated in different languages.
245
+ */
246
+ export interface LocalizedString2 {
247
+ en: string[] | string;
248
+ [k: string]: string;
249
+ }
250
+ /**
251
+ * A string that is translated in different languages.
252
+ */
253
+ export interface LocalizedString3 {
254
+ en: string[] | string;
255
+ /**
256
+ * @maxItems 10
257
+ */
258
+ [k: string]: string[];
259
+ }
260
+ /**
261
+ * A string that is translated in different languages.
262
+ */
263
+ export interface LocalizedString4 {
264
+ en: string[] | string;
265
+ [k: string]: string;
266
+ }
package/package.json CHANGED
@@ -1,6 +1,18 @@
1
1
  {
2
2
  "name": "heim",
3
- "version": "0.0.1",
4
- "main": "index.js",
5
- "license": "MIT"
3
+ "version": "0.1.0-alpha.2",
4
+ "description": "The library to create heim.ts files for heim apps.",
5
+ "license": "Apache-2.0",
6
+ "author": {
7
+ "name": "Josua Frank",
8
+ "email": "frank.josua@gmail.com"
9
+ },
10
+ "type": "module",
11
+ "types": "types.d.ts",
12
+ "scripts": {
13
+ "gen-types": "json2ts -i ../../types.schema.json -o gen/heim.d.ts --maxItems -1"
14
+ },
15
+ "devDependencies": {
16
+ "json-schema-to-typescript": "^15.0.4"
17
+ }
6
18
  }
package/tsconfig.json ADDED
@@ -0,0 +1,28 @@
1
+ {
2
+ "compilerOptions": {
3
+ // Environment setup & latest features
4
+ "lib": [
5
+ "ESNext"
6
+ ],
7
+ "target": "ESNext",
8
+ "module": "Preserve",
9
+ "moduleDetection": "force",
10
+ "jsx": "react-jsx",
11
+ "allowJs": true,
12
+ // Bundler mode
13
+ "moduleResolution": "bundler",
14
+ "allowImportingTsExtensions": true,
15
+ "verbatimModuleSyntax": true,
16
+ "noEmit": true,
17
+ // Best practices
18
+ "strict": true,
19
+ "skipLibCheck": true,
20
+ "noFallthroughCasesInSwitch": true,
21
+ "noUncheckedIndexedAccess": true,
22
+ "noImplicitOverride": true,
23
+ // Some stricter flags (disabled by default)
24
+ "noUnusedLocals": true,
25
+ "noUnusedParameters": true,
26
+ "noPropertyAccessFromIndexSignature": true
27
+ }
28
+ }
package/types.d.ts ADDED
@@ -0,0 +1,294 @@
1
+ import type { HeimTypes } from "./gen/heim";
2
+ import type { ComposeSpecification } from "./gen/compose";
3
+
4
+ declare global {
5
+ /**
6
+ * This is the main entry point for defining an application using the heim TypeScript library.
7
+ */
8
+ function defineApp(config: AppConfig): AppConfig;
9
+
10
+ // Types
11
+ type AppConfig = {
12
+ /**
13
+ * The manifest is the metadata of the app that describes its name, version, description, and other relevant information.
14
+ */
15
+ manifest: Manifest | ((ctx: ManifestContext) => Manifest);
16
+ /**
17
+ * The user interface configuration defines how the app's UI should be set up, including the services it provides, the ports it uses, and whether it requires authentication.
18
+ * It is optional, and if not provided, the app will only render the console as the user interface.
19
+ */
20
+ ui?: UserInterface | ((ctx: UserInterfaceContext) => UserInterface);
21
+ /**
22
+ * The compose configuration defines the Docker Compose specification for the app, including the services, volumes, networks, and other Docker resources that the app requires to run.
23
+ */
24
+ compose: Compose | ((ctx: ComposeContext) => Compose);
25
+ /**
26
+ * The migrations configuration defines the migrations (e.g. for databases) that need to be executed when the app is updated to a new version.
27
+ */
28
+ migrations?: Migration[] | ((ctx: MigrationContext) => Migration[]);
29
+ /**
30
+ * The backup configuration defines which volumes of the app should be backed up. It also allows specifying a custom backup command.
31
+ */
32
+ backup?: Backup | ((ctx: BackupContext) => Backup);
33
+ /**
34
+ * The restore configuration defines how to restore the app from a backup, including any custom restore commands that need to be executed before the restore process.
35
+ */
36
+ restore?: Restore | ((ctx: RestoreContext) => Restore);
37
+ /**
38
+ * The hooks configuration defines custom logic that should be executed at specific points in the app's lifecycle, such as before or after certain actions.
39
+ */
40
+ hooks?: Hooks | ((ctx: HooksContext) => Hooks);
41
+ };
42
+ type Manifest = HeimTypes["manifest"];
43
+ type ManifestContext = {};
44
+ type UserInterface = HeimTypes["ui"];
45
+ type UserInterfaceContext = {};
46
+ type Compose = ComposeSpecification;
47
+ type ComposeContext = {
48
+ data: {
49
+ /**
50
+ * Returns the path to a directory that can be used for shared storage between apps.
51
+ */
52
+ getSharedStorageDir(): string;
53
+ };
54
+
55
+ system: {
56
+ /**
57
+ * Returns a list of common IANA timezones, e.g. ["Europe/Berlin", "America/New_York", ...].
58
+ */
59
+ timezones(): string[];
60
+ /**
61
+ * Returns the system's current timezone in IANA format, e.g. "Europe/Berlin".
62
+ * This is determined by the host environment and may not be accurate if the user
63
+ * has recently changed their timezone or if the host environment does not provide this information.
64
+ */
65
+ timezone(): string;
66
+ };
67
+
68
+ input: {
69
+ /**
70
+ * If the storageKey is unknown, it prompts the user for input and returns the entered value.
71
+ * If the storageKey is known, it returns the previously entered value without prompting the user.
72
+ * @param storageKey A unique key to store the input value, e.g. "db-username"
73
+ * @param opts Options for the input prompt
74
+ */
75
+ text(
76
+ /**
77
+ * A unique key to store the input value, e.g. "db-username". The input value is stored under the provided storageKey and can be edited by the user later.
78
+ */
79
+ storageKey: string,
80
+ opts: {
81
+ /**
82
+ * The message to display to the user when prompting for input, e.g. "Enter your database username".
83
+ */
84
+ message: string;
85
+ /**
86
+ * An optional default value to pre-fill the input field, e.g. "admin".
87
+ */
88
+ defaultValue?: string;
89
+ /**
90
+ * If true, the input will allow multiple lines to be entered. Default is false.
91
+ */
92
+ multiLine?: boolean;
93
+ /**
94
+ * If true, the input will be masked (e.g. for passwords). Default is false.
95
+ */
96
+ mask?: string;
97
+ validate?: (value: string | undefined) => string | undefined;
98
+ },
99
+ ): string;
100
+ /**
101
+ * If the storageKey is unknown, it prompts the user for confirmation and returns the user's choice as a boolean.
102
+ * If the storageKey is known, it returns the previously entered value without prompting the user.
103
+ * @param storageKey A unique key to store the confirmation value, e.g. "ebnable-feature-x"
104
+ * @param opts Options for the confirmation prompt
105
+ */
106
+ confirm(
107
+ /**
108
+ * A unique key to store the confirmation value, e.g. "enable-feature-x". The confirmation value is stored under the provided storageKey and can be edited by the user later.
109
+ */
110
+ storageKey: string,
111
+ opts: {
112
+ /**
113
+ * The message to display to the user when prompting for confirmation, e.g. "Do you want to enable feature X?".
114
+ */
115
+ message: string;
116
+ /**
117
+ * An optional default value to pre-fill the confirmation, e.g. true (which would correspond to "Yes"). Default is false.
118
+ */
119
+ defaultValue?: boolean;
120
+ /**
121
+ * The text to display for the confirmation, e.g. "Yes". Default is "Yes".
122
+ */
123
+ confirmText?: string;
124
+ /**
125
+ * The text to display for the rejection, e.g. "No". Default is "No".
126
+ */
127
+ rejectText?: string;
128
+ },
129
+ ): boolean;
130
+ /**
131
+ * If the storageKey is unknown, it prompts the user to select one option from a list and returns the selected value.
132
+ * If the storageKey is known, it returns the previously selected value without prompting the user.
133
+ * @param storageKey A unique key to store the selected value, e.g. "storage-type"
134
+ * @param opts Options for the select prompt
135
+ */
136
+ select<V extends string>(
137
+ /**
138
+ * A unique key to store the selected value, e.g. "storage-type". The selected value is stored under the provided storageKey and can be edited by the user later.
139
+ */
140
+ storageKey: string,
141
+ opts: {
142
+ /**
143
+ * The message to display to the user when prompting for selection, e.g. "Select your storage type".
144
+ */
145
+ message: string;
146
+ /**
147
+ * A list of options to choose from, where each option has a value (which is returned when the option is selected) and a label (which is displayed to the user). For example: [{ value: "hdd", label: "Hard Drive" }, { value: "ssd", label: "Solid State Drive" }].
148
+ */
149
+ options: { value: V; label: string }[];
150
+ /**
151
+ * An optional default value to pre-select an option, e.g. "ssd". The defaultValue must match one of the values in the options array.
152
+ */
153
+ defaultValue?: V;
154
+ },
155
+ ): V;
156
+ /**
157
+ * If the storageKey is unknown, it prompts the user to select zero, one or more options from a list and returns the selected values as an array.
158
+ * If the storageKey is known, it returns the previously selected values without prompting the user.
159
+ * @param storageKey A unique key to store the selected values, e.g. "feature-flags". The selected values are stored under the provided storageKey and can be edited by the user later.
160
+ * @param opts Options for the multiselect prompt
161
+ */
162
+ multiselect<V extends string>(
163
+ /**
164
+ * A unique key to store the selected values, e.g. "feature-flags". The selected values are stored under the provided storageKey and can be edited by the user later.
165
+ */
166
+ storageKey: string,
167
+ opts: {
168
+ /**
169
+ * The message to display to the user when prompting for selection, e.g. "Select the video encoding backends you want to use".
170
+ */
171
+ message: string;
172
+ /**
173
+ * A list of options to choose from, where each option has a value (which is returned when the option is selected) and a label (which is displayed to the user). For example: [{ value: "h264", label: "H.264" }, { value: "vp9", label: "VP9" }, { value: "av1", label: "AV1" }].
174
+ */
175
+ options: { value: V; label: string }[];
176
+ /**
177
+ * An optional list of default values to pre-select options, e.g. ["h264", "vp9"]. The defaultValues must match the values in the options array.
178
+ */
179
+ defaultValue?: V[];
180
+ },
181
+ ): V[];
182
+ };
183
+
184
+ crypto: {
185
+ /**
186
+ * Generates a random password with the specified options.
187
+ * @param opts Options for password generation
188
+ */
189
+ password(opts?: {
190
+ /**
191
+ * The length of the generated password. Default is 16.
192
+ */
193
+ length?: number;
194
+ /**
195
+ * Exclude numbers from the generated password. Default is false.
196
+ */
197
+ excludeNumbers?: boolean;
198
+ /**
199
+ * Exclude special characters from the generated password. Default is false.
200
+ */
201
+ excludeSpecial?: boolean;
202
+ }): string;
203
+ };
204
+ };
205
+
206
+ type Migration = {
207
+ /**
208
+ * The version of the migration. This should be a string that can be compared to determine the order of migrations, e.g. "1.0.0", "2023-01-01", etc.
209
+ */
210
+ version: string;
211
+ /**
212
+ * A description of the migration, e.g. "Add new database schema for feature X".
213
+ */
214
+ description: string;
215
+ /**
216
+ * The command to execute for the migration. This can be a shell command or a script that performs the necessary changes for the migration.
217
+ */
218
+ command: string | string[];
219
+ };
220
+ type MigrationContext = {};
221
+
222
+ /**
223
+ * The backup configuration of the app.
224
+ */
225
+ type Backup = {
226
+ /**
227
+ * The volumes configuration defines which volumes of the app should be included or excluded in the backup. Each entry in the
228
+ * include or exclude list can be a volume name (string) to include or exclude the entire volume, or an object with a volume
229
+ * name and file filters to include or exclude only specific files within that volume. If neither the include nor the exclude
230
+ * list is set, all volumes will be included in the backup. If both lists are set, only the volumes in the include list that
231
+ * are not in the exclude list will be included in the backup.
232
+ */
233
+ volumes?: {
234
+ /**
235
+ * A list of volumes to include in the backup. Each entry can be a volume name (string) to include the entire volume,
236
+ * or an object with a volume name and file filters to include only specific files within that volume.
237
+ * If neither this list nor the exclude list is set, all volumes will be included.
238
+ * If both lists are set, only the volumes in the include list that are not in the exclude list will be included.
239
+ */
240
+ include?: (string | VolumeFilter)[];
241
+ /**
242
+ * A list of volumes to exclude from the backup. Each entry can be a volume name (string) to exclude the entire volume,
243
+ * or an object with a volume name and file filters to exclude only specific files within that volume.
244
+ * If neither this list nor the include list is set, all volumes will be included.
245
+ * If both lists are set, only the volumes in the include list that are not in the exclude list will be included.
246
+ */
247
+ exclude?: (string | VolumeFilter)[];
248
+ };
249
+ /**
250
+ * Additional files to include in the backup that are not part of any volume. The key is the name of the artifact and the value
251
+ * is the path to the file or directory to include in the backup.
252
+ * The key is used to identify the artifact in the backup and can be used in the restore process to get the artifact.
253
+ */
254
+ artifacts?: Record<string, string>;
255
+ };
256
+ type VolumeFilter = {
257
+ /**
258
+ * The name of the volume.
259
+ */
260
+ name: string;
261
+ /**
262
+ * File path patterns (globs) to include within this volume.
263
+ * If neither this nor the exclude property is set, the entire volume will be included.
264
+ * If both include and exclude are set, only the files that match the include patterns and do not match the exclude patterns will be included.
265
+ */
266
+ include?: string[];
267
+ /**
268
+ * File path patterns (globs) to exclude within this volume.
269
+ * If neither this nor the include property is set, the entire volume will be included.
270
+ * If both include and exclude are set, only the files that match the include patterns and do not match the exclude patterns will be included.
271
+ */
272
+ exclude?: string[];
273
+ };
274
+ type BackupContext = {
275
+ config: Map<string, string>;
276
+ exec: (service: string, command: string | string[]) => void;
277
+ log: Log;
278
+ };
279
+ type Restore = void;
280
+ type RestoreContext = {
281
+ config: Map<string, string>;
282
+ exec: (service: string, command: string | string[]) => void;
283
+ artifacts: Map<string, string>;
284
+ log: Log;
285
+ };
286
+ type Hooks = HeimTypes["hooks"];
287
+ type HooksContext = {};
288
+
289
+ type Log = {
290
+ info: (message: string) => void;
291
+ warning: (message: string) => void;
292
+ error: (message: string) => void;
293
+ };
294
+ }