@start9labs/start-sdk 0.3.6-alpha7 → 0.3.6-alpha9

package/package/lib/StartSdk.d.ts

@@ -0,0 +1,1182 @@
+/// <reference types="node" />
+import { RequiredDefault, Value } from "../../base/lib/actions/input/builder/value";
+import { InputSpec, ExtractInputSpecType, LazyBuild } from "../../base/lib/actions/input/builder/inputSpec";
+import { DefaultString, ListValueSpecText, Pattern, RandomString, UniqueBy, ValueSpecDatetime, ValueSpecText } from "../../base/lib/actions/input/inputSpecTypes";
+import { Variants } from "../../base/lib/actions/input/builder/variants";
+import { Action, Actions } from "../../base/lib/actions/setupActions";
+import { SyncOptions, ServiceInterfaceId, PackageId, HealthReceipt, ServiceInterfaceType, Effects } from "../../base/lib/types";
+import * as patterns from "../../base/lib/util/patterns";
+import { BackupSync, Backups } from "./backup/Backups";
+import { Daemons } from "./mainFn/Daemons";
+import { HealthCheckParams } from "./health/HealthCheck";
+import { checkPortListening } from "./health/checkFns/checkPortListening";
+import { List } from "../../base/lib/actions/input/builder/list";
+import { Install, InstallFn } from "./inits/setupInstall";
+import { SetupBackupsParams } from "./backup/setupBackups";
+import { Uninstall, UninstallFn } from "./inits/setupUninstall";
+import { changeOnFirstSuccess, cooldownTrigger } from "./trigger";
+import { UpdateServiceInterfaces } from "../../base/lib/interfaces/setupInterfaces";
+import { MultiHost, Scheme } from "../../base/lib/interfaces/Host";
+import { ServiceInterfaceBuilder } from "../../base/lib/interfaces/ServiceInterfaceBuilder";
+import { GetSystemSmtp } from "./util";
+import { nullIfEmpty } from "./util";
+import { CommandOptions, MountOptions, SubContainer } from "./util/SubContainer";
+import { Mounts } from "./mainFn/Mounts";
+import { Dependency } from "../../base/lib/dependencies/Dependency";
+import * as T from "../../base/lib/types";
+import { PathBuilder } from "../../base/lib/util/PathBuilder";
+import { CheckDependencies } from "../../base/lib/dependencies/dependencies";
+import { GetSslCertificate } from "./util";
+import { VersionGraph } from "./version";
+import { MaybeFn } from "../../base/lib/actions/setupActions";
+import { GetInput } from "../../base/lib/actions/setupActions";
+import { Run } from "../../base/lib/actions/setupActions";
+import * as actions from "../../base/lib/actions";
+export declare const SDKVersion: "0.3.6";
+type AnyNeverCond<T extends any[], Then, Else> = T extends [] ? Else : T extends [never, ...Array<any>] ? Then : T extends [any, ...infer U] ? AnyNeverCond<U, Then, Else> : never;
+export declare class StartSdk<Manifest extends T.Manifest, Store> {
+    readonly manifest: Manifest;
+    private constructor();
+    static of(): StartSdk<never, never>;
+    withManifest<Manifest extends T.Manifest = never>(manifest: Manifest): StartSdk<Manifest, Store>;
+    withStore<Store extends Record<string, any>>(): StartSdk<Manifest, Store>;
+    build(isReady: AnyNeverCond<[Manifest, Store], "Build not ready", true>): {
+        action: {
+            run: <Input extends Record<string, unknown>>(options: {
+                effects: Effects;
+                actionId: string;
+                input?: actions.RunActionInput<Input> | undefined;
+            }) => Promise<T.ActionResult | null>;
+            request: <T extends Action<string, any, any, Record<string, unknown>>>(effects: Effects, packageId: string, action: T, severity: T.ActionSeverity, options?: actions.ActionRequestOptions<T> | undefined) => Promise<null>;
+            requestOwn: <T_1 extends Action<string, Store, any, Record<string, unknown>>>(effects: Effects, action: T_1, severity: T.ActionSeverity, options?: actions.ActionRequestOptions<T_1> | undefined) => Promise<null>;
+            clearRequest: (effects: T.Effects, ...replayIds: string[]) => Promise<null>;
+        };
+        checkDependencies: <DependencyId extends keyof Manifest["dependencies"] & string = keyof Manifest["dependencies"] & string>(effects: Effects, packageIds?: DependencyId[] | undefined) => Promise<CheckDependencies<DependencyId>>;
+        serviceInterface: {
+            getOwn: <E extends Effects>(effects: E, id: ServiceInterfaceId) => import("./util").GetServiceInterface;
+            get: <E_1 extends Effects>(effects: E_1, opts: {
+                id: ServiceInterfaceId;
+                packageId: PackageId;
+            }) => import("./util").GetServiceInterface;
+            getAllOwn: <E_2 extends Effects>(effects: E_2) => import("../../base/lib/util/getServiceInterfaces").GetServiceInterfaces;
+            getAll: <E_3 extends Effects>(effects: E_3, opts: {
+                packageId: PackageId;
+            }) => import("../../base/lib/util/getServiceInterfaces").GetServiceInterfaces;
+        };
+        store: {
+            get: <E_4 extends Effects, StoreValue = unknown>(effects: E_4, packageId: string, path: PathBuilder<Store, StoreValue>) => import("./store/getStore").GetStore<Store, StoreValue>;
+            getOwn: <E_5 extends Effects, StoreValue_1 = unknown>(effects: E_5, path: PathBuilder<Store, StoreValue_1>) => import("./store/getStore").GetStore<Store, StoreValue_1>;
+            setOwn: <E_6 extends Effects, Path extends import("../../base/lib/util/PathBuilder").PathBuilderStored<Store, unknown>>(effects: E_6, path: Path, value: Path extends PathBuilder<Store, infer Value_1> ? Value_1 : never) => Promise<null>;
+        };
+        host: {
+            multi: (effects: Effects, id: string) => MultiHost;
+        };
+        nullIfEmpty: typeof nullIfEmpty;
+        runCommand: <A extends string>(effects: Effects, image: {
+            id: keyof Manifest["images"] & T.ImageId;
+            sharedRun?: boolean;
+        }, command: T.CommandType, options: CommandOptions & {
+            mounts?: {
+                path: string;
+                options: MountOptions;
+            }[] | undefined;
+        }, name: string) => Promise<{
+            stdout: string | Buffer;
+            stderr: string | Buffer;
+        }>;
+        /**
+         * TODO: rewrite this
+         * @description Use this function to create a static Action, including optional form input.
+         *
+         *   By convention, each Action should receive its own file.
+         *
+         * @param id
+         * @param metaData
+         * @param fn
+         * @returns
+         * @example
+         * In this example, we create an Action that prints a name to the console. We present a user
+         * with a form for optionally entering a temp name. If no temp name is provided, we use the name
+         * from the underlying `inputSpec.yaml` file. If no name is there, we use "Unknown". Then, we return
+         * a message to the user informing them what happened.
+         *
+         * ```
+          import { sdk } from '../sdk'
+          const { InputSpec, Value } = sdk
+          import { yamlFile } from '../file-models/inputSpec.yml'
+  
+          const input = InputSpec.of({
+            nameToPrint: Value.text({
+              name: 'Temp Name',
+              description: 'If no name is provided, the name from inputSpec will be used',
+              required: false,
+            }),
+          })
+  
+          export const nameToLog = sdk.createAction(
+            // id
+            'nameToLogs',
+  
+            // metadata
+            {
+              name: 'Name to Logs',
+              description: 'Prints "Hello [Name]" to the service logs.',
+              warning: null,
+              disabled: false,
+              input,
+              allowedStatuses: 'onlyRunning',
+              group: null,
+            },
+  
+            // the execution function
+            async ({ effects, input }) => {
+              const name =
+                input.nameToPrint || (await yamlFile.read(effects))?.name || 'Unknown'
+  
+              console.info(`Hello ${name}`)
+  
+              return {
+                version: '0',
+                message: `"Hello ${name}" has been written to the service logs. Open your logs to view it.`,
+                value: name,
+                copyable: true,
+                qr: false,
+              }
+            },
+          )
+         * ```
+         */
+        Action: {
+            withInput: <Id extends string, InputSpecType extends Record<string, any> | InputSpec<any, never> | InputSpec<any, any>, Type extends ExtractInputSpecType<InputSpecType> = ExtractInputSpecType<InputSpecType>>(id: Id, metadata: MaybeFn<Omit<T.ActionMetadata, "hasInput">>, inputSpec: InputSpecType, getInput: GetInput<Type>, run: Run<Type>) => Action<Id, unknown, InputSpecType, Type>;
+            withoutInput: <Id_1 extends string>(id: Id_1, metadata: MaybeFn<Omit<T.ActionMetadata, "hasInput">>, run: Run<{}>) => Action<Id_1, unknown, {}, {}>;
+        };
+        inputSpecConstants: {
+            smtpInputSpec: Value<{
+                selection: "disabled";
+                value: {};
+            } | {
+                selection: "system";
+                value: {
+                    customFrom: string | null | undefined;
+                };
+            } | {
+                selection: "custom";
+                value: {
+                    server: string;
+                    port: number;
+                    from: string;
+                    login: string;
+                    password: string | null | undefined;
+                };
+            }, never>;
+        };
+        /**
+         * @description Use this function to create a service interface.
+         * @param effects
+         * @param options
+         * @example
+         * In this example, we create a standard web UI
+         *
+         * ```
+          const ui = sdk.createInterface(effects, {
+            name: 'Web UI',
+            id: 'ui',
+            description: 'The primary web app for this service.',
+            type: 'ui',
+            hasPrimary: false,
+            masked: false,
+            schemeOverride: null,
+            username: null,
+            path: '',
+            search: {},
+          })
+         * ```
+         */
+        createInterface: (effects: Effects, options: {
+            /** The human readable name of this service interface. */
+            name: string;
+            /** A unique ID for this service interface. */
+            id: string;
+            /** The human readable description. */
+            description: string;
+            /** Not available until StartOS v0.4.0. If true, forces the user to select one URL (i.e. .onion, .local, or IP address) as the primary URL. This is needed by some services to function properly. */
+            hasPrimary: boolean;
+            /** Affects how the interface appears to the user. One of: 'ui', 'api', 'p2p'. */
+            type: ServiceInterfaceType;
+            /** (optional) prepends the provided username to all URLs. */
+            username: null | string;
+            /** (optional) appends the provided path to all URLs. */
+            path: string;
+            /** (optional) appends the provided query params to all URLs. */
+            search: Record<string, string>;
+            /** (optional) overrides the protocol prefix provided by the bind function.
+             *
+             * @example `ftp://`
+             */
+            schemeOverride: {
+                ssl: Scheme;
+                noSsl: Scheme;
+            } | null;
+            /** TODO Aiden how would someone include a password in the URL? Whether or not to mask the URLs on the screen, for example, when they contain a password */
+            masked: boolean;
+        }) => ServiceInterfaceBuilder;
+        getSystemSmtp: <E_7 extends Effects>(effects: E_7) => GetSystemSmtp;
+        getSslCerificate: <E_8 extends Effects>(effects: E_8, hostnames: string[], algorithm?: T.Algorithm) => GetSslCertificate;
+        HealthCheck: {
+            of(o: HealthCheckParams): HealthReceipt;
+        };
+        Dependency: {
+            /**
+             * @description Use this function to create a dependency for the service.
+             * @property {DependencyType} type
+             * @property {VersionRange} versionRange
+             * @property {string[]} healthChecks
+             */
+            of(data: Dependency["data"]): Dependency;
+        };
+        healthCheck: {
+            checkPortListening: typeof checkPortListening;
+            checkWebUrl: (effects: Effects, url: string, { timeout, successMessage, errorMessage, }?: {
+                timeout?: number | undefined;
+                successMessage?: string | undefined;
+                errorMessage?: string | undefined;
+            }) => Promise<import("./health/checkFns").HealthCheckResult>;
+            runHealthScript: (runCommand: string[], subcontainer: SubContainer, { timeout, errorMessage, message, }?: {
+                timeout?: number | undefined;
+                errorMessage?: string | undefined;
+                message?: ((res: string) => string) | undefined;
+            }) => Promise<import("./health/checkFns").HealthCheckResult>;
+        };
+        patterns: typeof patterns;
+        /**
+         * @description Use this function to list every Action offered by the service. Actions will be displayed in the provided order.
+         *
+         *   By convention, each Action should receive its own file in the "actions" directory.
+         * @example
+         *
+         * ```
+          import { sdk } from '../sdk'
+          import { config } from './config'
+          import { nameToLogs } from './nameToLogs'
+  
+          export const actions = sdk.Actions.of().addAction(config).addAction(nameToLogs)
+         * ```
+         */
+        Actions: {
+            new (actions: {}): Actions<Store, {}>;
+            of<Store_1>(): Actions<Store_1, {}>;
+        };
+        /**
+         * @description Use this function to determine which volumes are backed up when a user creates a backup, including advanced options.
+         * @example
+         * In this example, we back up the entire "main" volume and nothing else.
+         *
+         * ```
+          export const { createBackup, restoreBackup } = sdk.setupBackups(sdk.Backups.addVolume('main'))
+         * ```
+         * @example
+         * In this example, we back up the "main" and the "other" volume, but exclude hypothetical directory "excludedDir" from the "other".
+         *
+         * ```
+          export const { createBackup, restoreBackup } = sdk.setupBackups(sdk.Backups
+            .addVolume('main')
+            .addVolume('other', { exclude: ['path/to/excludedDir'] })
+          )
+         * ```
+         */
+        setupBackups: (options: SetupBackupsParams<Manifest>) => {
+            createBackup: T.ExpectedExports.createBackup;
+            restoreBackup: T.ExpectedExports.restoreBackup;
+        };
+        /**
+         * @description Use this function to set dependency information.
+         *
+         *   The function executes on service install, update, and inputSpec save. "input" will be of type `Input` for inputSpec save. It will be `null` for install and update.
+         * @example
+         * In this example, we create a static dependency on Hello World >=1.0.0:0, where Hello World must be running and passing its "webui" health check.
+         *
+         * ```
+          export const setDependencies = sdk.setupDependencies(
+            async ({ effects, input }) => {
+              return {
+                'hello-world': sdk.Dependency.of({
+                  type: 'running',
+                  versionRange: VersionRange.parse('>=1.0.0:0'),
+                  healthChecks: ['webui'],
+                }),
+              }
+            },
+          )
+         * ```
+         * @example
+         * In this example, we create a conditional dependency on Hello World based on a hypothetical "needsWorld" boolean in the store.
+         *
+         * ```
+          export const setDependencies = sdk.setupDependencies(
+            async ({ effects }) => {
+              if (sdk.store.getOwn(sdk.StorePath.needsWorld).const()) {
+                return {
+                  'hello-world': sdk.Dependency.of({
+                    type: 'running',
+                    versionRange: VersionRange.parse('>=1.0.0:0'),
+                    healthChecks: ['webui'],
+                  }),
+                }
+              }
+              return {}
+            },
+          )
+         * ```
+         */
+        setupDependencies: (fn: (options: {
+            effects: Effects;
+        }) => Promise<((Manifest["dependencies"] extends infer T_3 ? { [K_1 in keyof T_3]: Manifest["dependencies"][K_1]["optional"] extends false ? K_1 : never; } : never) extends infer T_2 ? { [K in keyof T_2]: Dependency; } : never) & ((Manifest["dependencies"] extends infer T_5 ? { [K_3 in keyof T_5]: Manifest["dependencies"][K_3]["optional"] extends true ? K_3 : never; } : never) extends infer T_4 ? { [K_2 in keyof T_4]?: Dependency | undefined; } : never)>) => (options: {
+            effects: Effects;
+        }) => Promise<null>;
+        setupInit: (versions: VersionGraph<Manifest["version"]>, install: Install<Manifest, Store>, uninstall: Uninstall<Manifest, Store>, setServiceInterfaces: UpdateServiceInterfaces<any>, setDependencies: (options: {
+            effects: Effects;
+        }) => Promise<void | null | undefined>, actions: Actions<Store, any>, exposedStore: T.ExposedStorePaths) => {
+            packageInit: T.ExpectedExports.packageInit;
+            packageUninit: T.ExpectedExports.packageUninit;
+            containerInit: T.ExpectedExports.containerInit;
+        };
+        /**
+         * @description Use this function to execute arbitrary logic *once*, on initial install only.
+         * @example
+         * In the this example, we bootstrap our Store with a random, 16-char admin password.
+         *
+         * ```
+          const install = sdk.setupInstall(async ({ effects }) => {
+            await sdk.store.setOwn(
+              effects,
+              sdk.StorePath.adminPassword,
+              utils.getDefaultString({
+                charset: 'a-z,A-Z,1-9,!,@,$,%,&,',
+                len: 16,
+              }),
+            )
+          })
+         * ```
+         */
+        setupInstall: (fn: InstallFn<Manifest, Store>) => Install<Manifest, Store>;
+        /**
+         * @description Use this function to determine how this service will be hosted and served. The function executes on service install, service update, and inputSpec save.
+         *
+         *   "input" will be of type `Input` for inputSpec save. It will be `null` for install and update.
+         *
+         *   To learn about creating multi-hosts and interfaces, check out the {@link https://docs.start9.com/packaging-guide/learn/interfaces documentation}.
+         * @param inputSpec - The inputSpec spec of this service as exported from /inputSpec/spec.
+         * @param fn - an async function that returns an array of interface receipts. The function always has access to `effects`; it has access to `input` only after inputSpec save, otherwise `input` will be null.
+         * @example
+         * In this example, we create two UIs from one multi-host, and one API from another multi-host.
+         *
+         * ```
+          export const setInterfaces = sdk.setupInterfaces(
+            inputSpecSpec,
+            async ({ effects, input }) => {
+              // ** UI multi-host **
+              const uiMulti = sdk.host.multi(effects, 'ui-multi')
+              const uiMultiOrigin = await uiMulti.bindPort(80, {
+                protocol: 'http',
+              })
+              // Primary UI
+              const primaryUi = sdk.createInterface(effects, {
+                name: 'Primary UI',
+                id: 'primary-ui',
+                description: 'The primary web app for this service.',
+                type: 'ui',
+                hasPrimary: false,
+                masked: false,
+                schemeOverride: null,
+                username: null,
+                path: '',
+                search: {},
+              })
+              // Admin UI
+              const adminUi = sdk.createInterface(effects, {
+                name: 'Admin UI',
+                id: 'admin-ui',
+                description: 'The admin web app for this service.',
+                type: 'ui',
+                hasPrimary: false,
+                masked: false,
+                schemeOverride: null,
+                username: null,
+                path: '/admin',
+                search: {},
+              })
+              // UI receipt
+              const uiReceipt = await uiMultiOrigin.export([primaryUi, adminUi])
+         
+              // ** API multi-host **
+              const apiMulti = sdk.host.multi(effects, 'api-multi')
+              const apiMultiOrigin = await apiMulti.bindPort(5959, {
+                protocol: 'http',
+              })
+              // API
+              const api = sdk.createInterface(effects, {
+                name: 'Admin API',
+                id: 'api',
+                description: 'The advanced API for this service.',
+                type: 'api',
+                hasPrimary: false,
+                masked: false,
+                schemeOverride: null,
+                username: null,
+                path: '',
+                search: {},
+              })
+              // API receipt
+              const apiReceipt = await apiMultiOrigin.export([api])
+         
+              // ** Return receipts **
+              return [uiReceipt, apiReceipt]
+            },
+          )
+         * ```
+         */
+        setupInterfaces: import("../../base/lib/interfaces/setupInterfaces").SetupServiceInterfaces;
+        setupMain: (fn: (o: {
+            effects: Effects;
+            started(onTerm: () => PromiseLike<void>): PromiseLike<null>;
+        }) => Promise<Daemons<Manifest, any>>) => T.ExpectedExports.main;
+        /**
+         * Use this function to execute arbitrary logic *once*, on uninstall only. Most services will not use this.
+         */
+        setupUninstall: (fn: UninstallFn<Manifest, Store>) => Uninstall<Manifest, Store>;
+        trigger: {
+            defaultTrigger: import("./trigger").Trigger;
+            cooldownTrigger: typeof cooldownTrigger;
+            changeOnFirstSuccess: typeof changeOnFirstSuccess;
+            successFailure: (o: {
+                duringSuccess: import("./trigger").Trigger;
+                duringError: import("./trigger").Trigger;
+            }) => import("./trigger").Trigger;
+        };
+        Mounts: {
+            of(): Mounts<Manifest>;
+        };
+        Backups: {
+            volumes: (...volumeNames: Array<Manifest["volumes"][number] & string>) => Backups<Manifest>;
+            addSets: (...options: BackupSync<Manifest["volumes"][number] & string>[]) => Backups<Manifest>;
+            withOptions: (options?: Partial<SyncOptions>) => Backups<Manifest>;
+        };
+        InputSpec: {
+            /**
+             * @description Use this function to define the inputSpec specification that will ultimately present to the user as validated form inputs.
+             *
+             *   Most form controls are supported, including text, textarea, number, toggle, select, multiselect, list, color, datetime, object (sub form), and union (conditional sub form).
+             * @example
+             * In this example, we define a inputSpec form with two value: name and makePublic.
+             *
+             * ```
+              import { sdk } from '../sdk'
+              const { InputSpec, Value } = sdk
+             
+              export const inputSpecSpec = InputSpec.of({
+                name: Value.text({
+                  name: 'Name',
+                  description:
+                    'When you launch the Hello World UI, it will display "Hello [Name]"',
+                  required: { default: 'World' },
+                }),
+                makePublic: Value.toggle({
+                  name: 'Make Public',
+                  description: 'Whether or not to expose the service to the network',
+                  default: false,
+                }),
+              })
+             * ```
+             */
+            of: <Spec extends Record<string, Value<any, never> | Value<any, Store>>>(spec: Spec) => InputSpec<{ [K_4 in keyof Spec]: Spec[K_4] extends Value<infer T_6, never> | Value<infer T_6, Store> ? T_6 : never; }, Store>;
+        };
+        Daemons: {
+            of(options: {
+                effects: Effects;
+                started: (onTerm: () => PromiseLike<void>) => PromiseLike<null>;
+                healthReceipts: HealthReceipt[];
+            }): Daemons<Manifest, never>;
+        };
+        List: {
+            /**
+             * @description Create a list of text inputs.
+             * @param a - attributes of the list itself.
+             * @param aSpec - attributes describing each member of the list.
+             */
+            text: typeof List.text;
+            /**
+             * @description Create a list of objects.
+             * @param a - attributes of the list itself.
+             * @param aSpec - attributes describing each member of the list.
+             */
+            obj: <Type_1 extends Record<string, any>>(a: {
+                name: string;
+                description?: string | null;
+                /** Presents a warning before adding/removing/editing a list item. */
+                warning?: string | null;
+                default?: [];
+                minLength?: number | null;
+                maxLength?: number | null;
+            }, aSpec: {
+                spec: InputSpec<Type_1, Store>;
+                /**
+                 * @description The ID of a required field on the inner object whose value will be used to display items in the list.
+                 * @example
+                 * In this example, we use the value of the `label` field to display members of the list.
+                 *
+                 * ```
+                  spec: InputSpec.of({
+                    label: Value.text({
+                      name: 'Label',
+                      required: false,
+                    })
+                  })
+                  displayAs: 'label',
+                  uniqueBy: null,
+                 * ```
+                 *
+                 */
+                displayAs?: string | null | undefined;
+                /**
+                 * @description The ID(s) of required fields on the inner object whose value(s) will be used to enforce uniqueness in the list.
+                 * @example
+                 * In this example, we use the `label` field to enforce uniqueness, meaning the label field must be unique from other entries.
+                 *
+                 * ```
+                  spec: InputSpec.of({
+                    label: Value.text({
+                      name: 'Label',
+                      required: { default: null },
+                    })
+                    pubkey: Value.text({
+                      name: 'Pubkey',
+                      required: { default: null },
+                    })
+                  })
+                  displayAs: 'label',
+                  uniqueBy: 'label',
+                 * ```
+                 * @example
+                 * In this example, we use the `label` field AND the `pubkey` field to enforce uniqueness, meaning both these fields must be unique from other entries.
+                 *
+                 * ```
+                  spec: InputSpec.of({
+                    label: Value.text({
+                      name: 'Label',
+                      required: { default: null },
+                    })
+                    pubkey: Value.text({
+                      name: 'Pubkey',
+                      required: { default: null },
+                    })
+                  })
+                  displayAs: 'label',
+                  uniqueBy: { all: ['label', 'pubkey'] },
+                 * ```
+                 */
+                uniqueBy?: UniqueBy | undefined;
+            }) => List<Type_1[], Store>;
+            /**
+             * @description Create a list of dynamic text inputs.
+             * @param a - attributes of the list itself.
+             * @param aSpec - attributes describing each member of the list.
+             */
+            dynamicText: (getA: LazyBuild<Store, {
+                name: string;
+                description?: string | null;
+                warning?: string | null;
+                default?: string[];
+                minLength?: number | null;
+                maxLength?: number | null;
+                disabled?: false | string;
+                generate?: null | RandomString;
+                spec: {
+                    masked?: boolean;
+                    placeholder?: string | null;
+                    minLength?: number | null;
+                    maxLength?: number | null;
+                    patterns: Pattern[];
+                    inputmode?: ListValueSpecText["inputmode"];
+                };
+            }>) => List<string[], Store>;
+        };
+        StorePath: PathBuilder<Store, Store>;
+        Value: {
+            /**
+             * @description Displays a boolean toggle to enable/disable
+             * @example
+             * ```
+              toggleExample: Value.toggle({
+                // required
+                name: 'Toggle Example',
+                default: true,
+             
+                // optional
+                description: null,
+                warning: null,
+                immutable: false,
+              }),
+             * ```
+             */
+            toggle: typeof Value.toggle;
+            /**
+             * @description Displays a text input field
+             * @example
+             * ```
+              textExample: Value.text({
+                // required
+                name: 'Text Example',
+                required: false,
+             
+                // optional
+                description: null,
+                placeholder: null,
+                warning: null,
+                generate: null,
+                inputmode: 'text',
+                masked: false,
+                minLength: null,
+                maxLength: null,
+                patterns: [],
+                immutable: false,
+              }),
+             * ```
+             */
+            text: typeof Value.text;
+            /**
+             * @description Displays a large textarea field for long form entry.
+             * @example
+             * ```
+              textareaExample: Value.textarea({
+                // required
+                name: 'Textarea Example',
+                required: false,
+             
+                // optional
+                description: null,
+                placeholder: null,
+                warning: null,
+                minLength: null,
+                maxLength: null,
+                immutable: false,
+              }),
+             * ```
+             */
+            textarea: typeof Value.textarea;
+            /**
+             * @description Displays a number input field
+             * @example
+             * ```
+              numberExample: Value.number({
+                // required
+                name: 'Number Example',
+                required: false,
+                integer: true,
+             
+                // optional
+                description: null,
+                placeholder: null,
+                warning: null,
+                min: null,
+                max: null,
+                immutable: false,
+                step: null,
+                units: null,
+              }),
+             * ```
+             */
+            number: typeof Value.number;
+            /**
+             * @description Displays a browser-native color selector.
+             * @example
+             * ```
+              colorExample: Value.color({
+                // required
+                name: 'Color Example',
+                required: false,
+             
+                // optional
+                description: null,
+                warning: null,
+                immutable: false,
+              }),
+             * ```
+             */
+            color: typeof Value.color;
+            /**
+             * @description Displays a browser-native date/time selector.
+             * @example
+             * ```
+              datetimeExample: Value.datetime({
+                // required
+                name: 'Datetime Example',
+                required: false,
+             
+                // optional
+                description: null,
+                warning: null,
+                immutable: false,
+                inputmode: 'datetime-local',
+                min: null,
+                max: null,
+              }),
+             * ```
+             */
+            datetime: typeof Value.datetime;
+            /**
+             * @description Displays a select modal with radio buttons, allowing for a single selection.
+             * @example
+             * ```
+              selectExample: Value.select({
+                // required
+                name: 'Select Example',
+                required: false,
+                values: {
+                  radio1: 'Radio 1',
+                  radio2: 'Radio 2',
+                },
+             
+                // optional
+                description: null,
+                warning: null,
+                immutable: false,
+                disabled: false,
+              }),
+             * ```
+             */
+            select: typeof Value.select;
+            /**
+             * @description Displays a select modal with checkboxes, allowing for multiple selections.
+             * @example
+             * ```
+              multiselectExample: Value.multiselect({
+                // required
+                name: 'Multiselect Example',
+                values: {
+                  option1: 'Option 1',
+                  option2: 'Option 2',
+                },
+                default: [],
+             
+                // optional
+                description: null,
+                warning: null,
+                immutable: false,
+                disabled: false,
+                minlength: null,
+                maxLength: null,
+              }),
+             * ```
+             */
+            multiselect: typeof Value.multiselect;
+            /**
+             * @description Display a collapsable grouping of additional fields, a "sub form". The second value is the inputSpec spec for the sub form.
+             * @example
+             * ```
+              objectExample: Value.object(
+                {
+                  // required
+                  name: 'Object Example',
+             
+                  // optional
+                  description: null,
+                  warning: null,
+                },
+                InputSpec.of({}),
+              ),
+             * ```
+             */
+            object: typeof Value.object;
+            /**
+             * @description Displays a dropdown, allowing for a single selection. Depending on the selection, a different object ("sub form") is presented.
+             * @example
+             * ```
+              unionExample: Value.union(
+                {
+                  // required
+                  name: 'Union Example',
+                  required: false,
+             
+                  // optional
+                  description: null,
+                  warning: null,
+                  disabled: false,
+                  immutable: false,
+                },
+                Variants.of({
+                  option1: {
+                    name: 'Option 1',
+                    spec: InputSpec.of({}),
+                  },
+                  option2: {
+                    name: 'Option 2',
+                    spec: InputSpec.of({}),
+                  },
+                }),
+              ),
+             * ```
+             */
+            union: typeof Value.union;
+            /**
+             * @description Presents an interface to add/remove/edit items in a list.
+             * @example
+             * In this example, we create a list of text inputs.
+             *
+             * ```
+              listExampleText: Value.list(
+                List.text(
+                  {
+                    // required
+                    name: 'Text List',
+    
+                    // optional
+                    description: null,
+                    warning: null,
+                    default: [],
+                    minLength: null,
+                    maxLength: null,
+                  },
+                  {
+                    // required
+                    patterns: [],
+    
+                    // optional
+                    placeholder: null,
+                    generate: null,
+                    inputmode: 'url',
+                    masked: false,
+                    minLength: null,
+                    maxLength: null,
+                  },
+                ),
+              ),
+             * ```
+             * @example
+             * In this example, we create a list of objects.
+             *
+             * ```
+              listExampleObject: Value.list(
+                List.obj(
+                  {
+                    // required
+                    name: 'Object List',
+    
+                    // optional
+                    description: null,
+                    warning: null,
+                    default: [],
+                    minLength: null,
+                    maxLength: null,
+                  },
+                  {
+                    // required
+                    spec: InputSpec.of({}),
+    
+                    // optional
+                    displayAs: null,
+                    uniqueBy: null,
+                  },
+                ),
+              ),
+             * ```
+             */
+            list: typeof Value.list;
+            dynamicToggle: (a: LazyBuild<Store, {
+                name: string;
+                description?: string | null;
+                /** Presents a warning prompt before permitting the value to change. */
+                warning?: string | null;
+                default: boolean;
+                disabled?: false | string;
+            }>) => Value<boolean, Store>;
+            dynamicText: (getA: LazyBuild<Store, {
+                name: string;
+                description?: string | null;
+                /** Presents a warning prompt before permitting the value to change. */
+                warning?: string | null;
+                /**
+                 * @description Determines if the field is required. If so, optionally provide a default value.
+                 * @type { false | { default: string | RandomString | null } }
+                 * @example required: false
+                 * @example required: { default: null }
+                 * @example required: { default: 'World' }
+                 * @example required: { default: { charset: 'abcdefg', len: 16 } }
+                 */
+                required: RequiredDefault<DefaultString>;
+                /**
+                 * @description Mask (aka camouflage) text input with dots: ● ● ●
+                 * @default false
+                 */
+                masked?: boolean;
+                placeholder?: string | null;
+                minLength?: number | null;
+                maxLength?: number | null;
+                /**
+                 * @description A list of regular expressions to which the text must conform to pass validation. A human readable description is provided in case the validation fails.
+                 * @default []
+                 * @example
+                 * ```
+                  [
+                    {
+                      regex: "[a-z]",
+                      description: "May only contain lower case letters from the English alphabet."
+                    }
+                  ]
+                 * ```
+                 */
+                patterns?: Pattern[];
+                /**
+                 * @description Informs the browser how to behave and which keyboard to display on mobile
+                 * @default "text"
+                 */
+                inputmode?: ValueSpecText["inputmode"];
+                /**
+                 * @description Displays a button that will generate a random string according to the provided charset and len attributes.
+                 */
+                generate?: null | RandomString;
+            }>) => Value<string | null | undefined, Store>;
+            dynamicTextarea: (getA: LazyBuild<Store, {
+                name: string;
+                description?: string | null;
+                /** Presents a warning prompt before permitting the value to change. */
+                warning?: string | null;
+                /**
+                 * @description Unlike other "required" fields, for textarea this is a simple boolean.
+                 */
+                required: boolean;
+                minLength?: number | null;
+                maxLength?: number | null;
+                placeholder?: string | null;
+                disabled?: false | string;
+                generate?: null | RandomString;
+            }>) => Value<string, Store>;
+            dynamicNumber: (getA: LazyBuild<Store, {
+                name: string;
+                description?: string | null;
+                /** Presents a warning prompt before permitting the value to change. */
+                warning?: string | null;
+                /**
+                 * @description Determines if the field is required. If so, optionally provide a default value.
+                 * @type { false | { default: number | null } }
+                 * @example required: false
+                 * @example required: { default: null }
+                 * @example required: { default: 7 }
+                 */
+                required: RequiredDefault<number>;
+                min?: number | null;
+                max?: number | null;
+                /**
+                 * @description How much does the number increase/decrease when using the arrows provided by the browser.
+                 * @default 1
+                 */
+                step?: number | null;
+                /**
+                 * @description Requires the number to be an integer.
+                 */
+                integer: boolean;
+                /**
+                 * @description Optionally display units to the right of the input box.
+                 */
+                units?: string | null;
+                placeholder?: string | null;
+                disabled?: false | string;
+            }>) => Value<number | null | undefined, Store>;
+            dynamicColor: (getA: LazyBuild<Store, {
+                name: string;
+                description?: string | null;
+                /** Presents a warning prompt before permitting the value to change. */
+                warning?: string | null;
+                /**
+                 * @description Determines if the field is required. If so, optionally provide a default value.
+                 * @type { false | { default: string | null } }
+                 * @example required: false
+                 * @example required: { default: null }
+                 * @example required: { default: 'ffffff' }
+                 */
+                required: RequiredDefault<string>;
+                disabled?: false | string;
+            }>) => Value<string | null | undefined, Store>;
+            dynamicDatetime: (getA: LazyBuild<Store, {
+                name: string;
+                description?: string | null;
+                /** Presents a warning prompt before permitting the value to change. */
+                warning?: string | null;
+                /**
+                 * @description Determines if the field is required. If so, optionally provide a default value.
+                 * @type { false | { default: string | null } }
+                 * @example required: false
+                 * @example required: { default: null }
+                 * @example required: { default: '1985-12-16 18:00:00.000' }
+                 */
+                required: RequiredDefault<string>;
+                /**
+                 * @description Informs the browser how to behave and which date/time component to display.
+                 * @default "datetime-local"
+                 */
+                inputmode?: ValueSpecDatetime["inputmode"];
+                min?: string | null;
+                max?: string | null;
+                disabled?: false | string;
+            }>) => Value<string | null | undefined, Store>;
+            dynamicSelect: (getA: LazyBuild<Store, {
+                name: string;
+                description?: string | null;
+                /** Presents a warning prompt before permitting the value to change. */
+                warning?: string | null;
+                /**
+                 * @description Determines if the field is required. If so, optionally provide a default value from the list of values.
+                 * @type { false | { default: string | null } }
+                 * @example required: false
+                 * @example required: { default: null }
+                 * @example required: { default: 'radio1' }
+                 */
+                required: RequiredDefault<string>;
+                /**
+                 * @description A mapping of unique radio options to their human readable display format.
+                 * @example
+                 * ```
+                  {
+                    radio1: "Radio 1"
+                    radio2: "Radio 2"
+                    radio3: "Radio 3"
+                  }
+                 * ```
+                 */
+                values: Record<string, string>;
+                /**
+                 * @options
+                 *   - false - The field can be modified.
+                 *   - string - The field cannot be modified. The provided text explains why.
+                 *   - string[] - The field can be modified, but the values contained in the array cannot be selected.
+                 * @default false
+                 */
+                disabled?: false | string | string[];
+            }>) => Value<string | null | undefined, Store>;
+            dynamicMultiselect: (getA: LazyBuild<Store, {
+                name: string;
+                description?: string | null;
+                /** Presents a warning prompt before permitting the value to change. */
+                warning?: string | null;
+                /**
+                 * @description A simple list of which options should be checked by default.
+                 */
+                default: string[];
+                /**
+                 * @description A mapping of checkbox options to their human readable display format.
+                 * @example
+                 * ```
+                  {
+                    option1: "Option 1"
+                    option2: "Option 2"
+                    option3: "Option 3"
+                  }
+                 * ```
+                 */
+                values: Record<string, string>;
+                minLength?: number | null;
+                maxLength?: number | null;
+                /**
+                 * @options
+                 *   - false - The field can be modified.
+                 *   - string - The field cannot be modified. The provided text explains why.
+                 *   - string[] - The field can be modified, but the values contained in the array cannot be selected.
+                 * @default false
+                 */
+                disabled?: false | string | string[];
+            }>) => Value<string[], Store>;
+            filteredUnion: <Required_1 extends RequiredDefault<string>, Type_2 extends Record<string, any>>(getDisabledFn: LazyBuild<Store, string[]>, a: {
+                name: string;
+                description?: string | null | undefined;
+                warning?: string | null | undefined;
+                required: Required_1;
+            }, aVariants: Variants<Type_2, Store> | Variants<Type_2, never>) => Value<Required_1 extends {
+                default: unknown;
+            } ? Type_2 : Type_2 | null | undefined, Store>;
+            dynamicUnion: <Required_2 extends RequiredDefault<string>, Type_3 extends Record<string, any>>(getA: LazyBuild<Store, {
+                name: string;
+                description?: string | null | undefined;
+                /** Presents a warning prompt before permitting the value to change. */
+                warning?: string | null | undefined;
+                /**
+                 * @description Determines if the field is required. If so, optionally provide a default value from the list of variants.
+                 * @type { false | { default: string | null } }
+                 * @example required: false
+                 * @example required: { default: null }
+                 * @example required: { default: 'variant1' }
+                 */
+                required: Required_2;
+                /**
+                 * @options
+                 *   - false - The field can be modified.
+                 *   - string - The field cannot be modified. The provided text explains why.
+                 *   - string[] - The field can be modified, but the values contained in the array cannot be selected.
+                 * @default false
+                 */
+                disabled: false | string | string[];
+            }>, aVariants: Variants<Type_3, Store> | Variants<Type_3, never>) => Value<Type_3 | null | undefined, Store>;
+        };
+        Variants: {
+            of: <VariantValues extends {
+                [x: string]: {
+                    name: string;
+                    spec: InputSpec<any, Store>;
+                };
+            }>(a: VariantValues) => Variants<{ [K_5 in keyof VariantValues]: {
+                selection: K_5;
+                value: VariantValues[K_5]["spec"] extends InputSpec<infer B extends Record<string, any>, never> | InputSpec<infer B extends Record<string, any>, Store> ? B : never;
+            }; }[keyof VariantValues], Store>;
+        };
+        restart: (effects: Effects) => Promise<null>;
+        shutdown: (effects: Effects) => Promise<null>;
+        setDependencies: (effects: Effects, options: {
+            dependencies: T.Dependencies;
+        }) => Promise<null>;
+        getDependencies: (effects: Effects) => Promise<T.DependencyRequirement[]>;
+        mount: (effects: Effects, options: {
+            location: string;
+            target: {
+                packageId: string;
+                volumeId: string;
+                subpath: string | null;
+                readonly: boolean;
+            };
+        }) => Promise<string>;
+        getInstalledPackages: (effects: Effects) => Promise<string[]>;
+        exposeForDependents: (effects: Effects, options: {
+            paths: string[];
+        }) => Promise<null>;
+        getServicePortForward: (effects: Effects, options: {
+            packageId?: string | undefined;
+            hostId: string;
+            internalPort: number;
+        }) => Promise<T.LanInfo>;
+        clearBindings: (effects: Effects, options: {
+            except: {
+                id: string;
+                internalPort: number;
+            }[];
+        }) => Promise<null>;
+        getContainerIp: (effects: Effects) => Promise<string>;
+        getSslKey: (effects: Effects, options: {
+            hostnames: string[];
+            algorithm?: "ecdsa" | "ed25519" | undefined;
+        }) => Promise<string>;
+        setDataVersion: (effects: Effects, options: {
+            version: string;
+        }) => Promise<null>;
+        getDataVersion: (effects: Effects) => Promise<string | null>;
+    };
+}
+export declare function runCommand<Manifest extends T.Manifest>(effects: Effects, image: {
+    id: keyof Manifest["images"] & T.ImageId;
+    sharedRun?: boolean;
+}, command: string | [string, ...string[]], options: CommandOptions & {
+    mounts?: {
+        path: string;
+        options: MountOptions;
+    }[];
+}, name: string): Promise<{
+    stdout: string | Buffer;
+    stderr: string | Buffer;
+}>;
+export {};