paratix 0.9.0 → 0.12.2

package/dist/index.d.ts

@@ -1,6 +1,5 @@
-import { E as Environment, M as Module, a as ModuleMetaEntry, b as MetaEnvironmentValue, c as EnvironmentMetaEntry, d as SshdPortMetaEntry, e as SystemHostMetaEntry, f as SystemRebootMetaEntry, g as ModuleResult, h as ExecResult, i as ModuleStatus, j as SshConnection, O as OrchestrationStep, S as ServerDefinition } from './types-Cl2Muw1x.js';
-export { k as EnvironmentValue, l as ExecOptions, N as NEEDS_APPLY, m as SshConfig } from './types-Cl2Muw1x.js';
-export { a as apt, b as archive, c as command, d as compose, e as cron, f as download, g as file, h as git, i as group, j as hostname, m as mount, n as net, o as op, p as package, q as quadlet, r as releaseUpgrade, k as rsync, s as script, l as service, t as ssh, u as sshd, v as sysctl, w as system, x as systemd, y as ufw, z as user } from './user-B9lkXr0X.js';
+import { E as Environment, M as Module, a as ModuleMetaEntry, b as MetaEnvironmentValue, c as EnvironmentMetaEntry, S as SshdPortMetaEntry, d as SystemHostMetaEntry, e as SystemRebootMetaEntry, f as ModuleResult, g as ExecResult, h as ModuleStatus, i as SshConnection, O as OrchestrationStep, j as ShutdownSignal, k as ServerDefinition } from './index-udpAybq3.js';
+export { l as EnvironmentValue, m as ExecOptions, N as NEEDS_APPLY, n as SshConfig, o as apt, p as archive, q as command, r as compose, s as cron, t as download, u as file, v as git, w as group, x as hostname, y as mount, z as net, A as op, B as package, C as quadlet, D as releaseUpgrade, F as rsync, G as script, H as service, I as ssh, J as sshd, K as swap, L as sysctl, P as system, Q as systemd, R as timer, T as ufw, U as user } from './index-udpAybq3.js';
 
 /**
  * Fail the run if a condition on the current env is not satisfied.
@@ -36,6 +35,10 @@ declare function fail(message: string): Module;
  * Pause execution and wait for the operator to press Enter.
  * Useful for interactive confirmation during a run.
  *
+ * Honors the runner's prompt abort signal: a SIGINT during the pause cancels
+ * the wait, removes the stdin `data` listener, and rejects the apply promise
+ * with the signal's abort reason.
+ *
  * @param message - Prompt shown to the operator. Defaults to `"Press enter to continue..."`.
  * @returns A Module that pauses execution.
  */
@@ -97,6 +100,32 @@ type WhenFunction = {
 } & typeof baseWhen;
 declare const when: WhenFunction;
 
+/**
+ * Resolve a single env key to its concrete value.
+ * Lazy function values are awaited; plain primitive values are returned as-is.
+ *
+ * @param environment - The env map to look up the key in.
+ * @param key - The key to resolve.
+ * @returns The resolved primitive value.
+ * @throws {Error} When the key is not present in `environment`.
+ */
+declare function resolveEnvironment(environment: Environment, key: string): Promise<boolean | number | string>;
+
+/**
+ * Public API helper that returns the current first-run flag.
+ *
+ * Returns `true` only when called from inside a
+ * `withCliProcessEnvironment` body whose `firstRun` option was `true`.
+ * Outside of a CLI invocation, or when the flag was not set, the helper
+ * returns `false`. The helper is async-context aware: a playbook that
+ * schedules its own microtasks/timers within the CLI body keeps observing
+ * the same flag, while concurrent work outside that body sees `false`.
+ *
+ * @returns `true` when the current async context is a first-run CLI body.
+ */
+declare function isFirstRun(): boolean;
+
+type MetaValueType = "boolean" | "number" | "string";
 type BooleanEnvironmentMetaEntry = {
     valueType: "boolean";
 } & EnvironmentMetaEntry;
@@ -107,7 +136,7 @@ type NumberEnvironmentMetaEntry = {
 type StringEnvironmentMetaEntry = {
     valueType: "string";
 } & EnvironmentMetaEntry;
-declare function environmentMeta(name: string, value: MetaEnvironmentValue, valueType?: "boolean" | "number" | "string"): EnvironmentMetaEntry;
+declare function environmentMeta(name: string, value: MetaEnvironmentValue, valueType?: MetaValueType): EnvironmentMetaEntry;
 declare function sshdPortMeta(port: number): SshdPortMetaEntry;
 declare function systemHostMeta(host: string): SystemHostMetaEntry;
 declare function systemRebootMeta(): SystemRebootMetaEntry;
@@ -132,7 +161,22 @@ declare function environmentToMetaEntries(environment: Environment): ModuleMetaE
 declare function diffEnvironmentToMetaEntries(original: Environment, current: Environment): ModuleMetaEntry[] | undefined;
 
 declare function failed(message: string): ModuleResult;
-declare function failedCommand(message: string, result: ExecResult): ModuleResult;
+/**
+ * Build a `failed` ModuleResult from an `ExecResult`. When `secrets` is
+ * provided, every secret variant is masked in the rendered error message and
+ * in the stored stdout/stderr so the hash, signed URL, or token never leaks
+ * through `failedCommand`'s output. Callers that already pass `secrets` to
+ * `ssh.exec` should forward the same list here so the failure path stays
+ * symmetric with the success path.
+ *
+ * @param message - Human-readable summary of the failure context.
+ * @param result - The non-zero `ExecResult` returned by `ssh.exec` (typically
+ *   captured via `ignoreExitCode: true`).
+ * @param secrets - Optional list of secret strings to mask in the rendered
+ *   error message and the captured stdout/stderr.
+ * @returns A failed ModuleResult whose error is a {@link CommandError}.
+ */
+declare function failedCommand(message: string, result: ExecResult, secrets?: string[]): ModuleResult;
 
 type SignalHooks = {
     onSignalFinished?: (status: ModuleStatus) => void;
@@ -151,7 +195,7 @@ type RecipeModule = {
     apply: (ssh: null | SshConnection, environment: Environment, options?: {
         onChildStep?: (step: OrchestrationStep) => Promise<void>;
         onSignalStep?: (step: OrchestrationStep) => Promise<void>;
-        shutdownSignal?: () => NodeJS.Signals | null;
+        shutdownSignal?: () => null | ShutdownSignal;
         signalHooks?: SignalHooks;
         verbose?: boolean;
     }) => Promise<ModuleResult>;
@@ -213,4 +257,4 @@ declare function server(config: ServerDefinition): ServerDefinition;
  */
 declare function shellQuote(s: string): string;
 
-export { Environment, EnvironmentMetaEntry, ExecResult, MetaEnvironmentValue, Module, ModuleMetaEntry, ModuleResult, ServerDefinition, SshConnection, SshdPortMetaEntry, SystemHostMetaEntry, SystemRebootMetaEntry, assert, assertValidModuleMetaEntries, assertValidModuleMetaEntry, debug, diffEnvironmentToMetaEntries, environmentMeta, environmentToMetaEntries, fail, failed, failedCommand, firstRun, isBooleanEnvironmentMetaEntry, isEnvironmentMetaEntry, isLazyEnvironmentMetaEntry, isNumberEnvironmentMetaEntry, isSshdPortMetaEntry, isStringEnvironmentMetaEntry, isSystemHostMetaEntry, isSystemRebootMetaEntry, mergeEnvironmentFromMeta, meta, pause, recipe, server, shellQuote, signals, sshdPortMeta, systemHostMeta, systemRebootMeta, when };
+export { Environment, EnvironmentMetaEntry, ExecResult, MetaEnvironmentValue, Module, ModuleMetaEntry, ModuleResult, ServerDefinition, ShutdownSignal, SshConnection, SshdPortMetaEntry, SystemHostMetaEntry, SystemRebootMetaEntry, assert, assertValidModuleMetaEntries, assertValidModuleMetaEntry, debug, diffEnvironmentToMetaEntries, environmentMeta, environmentToMetaEntries, fail, failed, failedCommand, firstRun, isBooleanEnvironmentMetaEntry, isEnvironmentMetaEntry, isFirstRun, isLazyEnvironmentMetaEntry, isNumberEnvironmentMetaEntry, isSshdPortMetaEntry, isStringEnvironmentMetaEntry, isSystemHostMetaEntry, isSystemRebootMetaEntry, mergeEnvironmentFromMeta, meta, pause, recipe, resolveEnvironment, server, shellQuote, signals, sshdPortMeta, systemHostMeta, systemRebootMeta, when };