paratix 0.0.1 → 0.1.0

package/dist/index.js

@@ -0,0 +1,620 @@
+import {
+  printCommandFailure,
+  printModuleResult,
+  printRecipeHeader,
+  runSignalModules,
+  startModuleSpinner,
+  withRecipeOutputScope
+} from "./chunk-DUIGEB2J.js";
+import {
+  NEEDS_APPLY,
+  apt,
+  archive,
+  command,
+  compose,
+  cron,
+  download,
+  failed,
+  failedCommand,
+  file,
+  git,
+  group,
+  hostname,
+  mount,
+  net,
+  op,
+  pkg,
+  releaseUpgrade,
+  rsync,
+  script,
+  service,
+  ssh,
+  sshd,
+  sysctl,
+  system,
+  systemd,
+  ufw,
+  user
+} from "./chunk-ULJMW23T.js";
+import {
+  CommandError,
+  assertValidModuleMetaEntries,
+  assertValidModuleMetaEntry,
+  diffEnvironmentToMetaEntries,
+  environmentMeta,
+  environmentToMetaEntries,
+  isBooleanEnvironmentMetaEntry,
+  isEnvironmentMetaEntry,
+  isLazyEnvironmentMetaEntry,
+  isNumberEnvironmentMetaEntry,
+  isSshdPortMetaEntry,
+  isStringEnvironmentMetaEntry,
+  isSystemHostMetaEntry,
+  isSystemRebootMetaEntry,
+  mergeEnvironmentFromMeta,
+  meta,
+  shellQuote,
+  sshdPortMeta,
+  systemHostMeta,
+  systemRebootMeta,
+  validateSshConfig
+} from "./chunk-G3BMCQKU.js";
+
+// src/builtins.ts
+function assert(condition, message) {
+  return {
+    _dryRunBlocker: true,
+    // eslint-disable-next-line @typescript-eslint/require-await -- Interface requires async
+    async apply(_ssh, environment) {
+      if (condition(environment)) {
+        return { status: "ok" };
+      }
+      return failed(`[assert] ${message}`);
+    },
+    // eslint-disable-next-line @typescript-eslint/require-await -- Interface requires async
+    async check(_ssh, environment) {
+      return condition(environment) ? "ok" : NEEDS_APPLY;
+    },
+    name: `assert: ${message}`
+  };
+}
+function debug(message) {
+  return {
+    // eslint-disable-next-line @typescript-eslint/require-await -- Interface requires async
+    async apply() {
+      console.log(`  [debug] ${message}`);
+      return { status: "ok" };
+    },
+    // eslint-disable-next-line @typescript-eslint/require-await -- Interface requires async
+    async check() {
+      return NEEDS_APPLY;
+    },
+    name: `debug: ${message}`
+  };
+}
+function fail(message) {
+  return {
+    _dryRunBlocker: true,
+    // eslint-disable-next-line @typescript-eslint/require-await -- Interface requires async
+    async apply() {
+      return failed(`[fail] ${message}`);
+    },
+    // eslint-disable-next-line @typescript-eslint/require-await -- Interface requires async
+    async check() {
+      return NEEDS_APPLY;
+    },
+    name: `fail: ${message}`
+  };
+}
+function pause(message) {
+  return {
+    async apply() {
+      const promptText = message ?? "Press enter to continue...";
+      process.stdout.write(`  [pause] ${promptText} `);
+      await new Promise((resolve) => {
+        process.stdin.once("data", () => {
+          process.stdin.pause();
+          resolve();
+        });
+      });
+      return { status: "ok" };
+    },
+    // eslint-disable-next-line @typescript-eslint/require-await -- Interface requires async
+    async check() {
+      return NEEDS_APPLY;
+    },
+    name: message == null ? "pause" : `pause: ${message}`
+  };
+}
+function isFirstRunEnabled(environment) {
+  return environment.PARATIX_FIRST_RUN === "true" || environment.FIRST_RUN === true;
+}
+var firstRun = {
+  /**
+   * Stop the current run successfully when Paratix was invoked with `--first-run`.
+   * Useful as an explicit stage boundary in scaffolded playbooks.
+   *
+   * @param message - Optional note shown in the module name.
+   * @returns A local module that stops the run only during first-run execution.
+   */
+  stop(message) {
+    const moduleName = message == null ? "firstRun.stop" : `firstRun.stop: ${message}`;
+    return {
+      _dryRunBlocker: true,
+      // eslint-disable-next-line @typescript-eslint/require-await -- Interface requires async
+      async apply(_ssh, environment) {
+        if (!isFirstRunEnabled(environment)) {
+          return { status: "ok" };
+        }
+        return {
+          _dryRunDetail: "(first-run stop)",
+          _stopRun: true,
+          status: "ok"
+        };
+      },
+      // eslint-disable-next-line @typescript-eslint/require-await -- Interface requires async
+      async check(_ssh, environment) {
+        return isFirstRunEnabled(environment) ? NEEDS_APPLY : "ok";
+      },
+      local: true,
+      name: moduleName
+    };
+  }
+};
+var signals = {
+  /**
+   * Flush all currently pending signals for the active scope.
+   * Signals remain scope-local:
+   * - in a recipe, this flushes that recipe's signals
+   * - at top level, this flushes `server(...).signals`
+   *
+   * @param message - Optional note shown in the module name.
+   * @returns A local control module that requests an immediate signal flush.
+   */
+  flush(message) {
+    const moduleName = message == null ? "signals.flush" : `signals.flush: ${message}`;
+    return {
+      _dryRunBlocker: true,
+      // eslint-disable-next-line @typescript-eslint/require-await -- Interface requires async
+      async apply() {
+        return {
+          _dryRunDetail: "(dry-run, pending signals not executed)",
+          _flushSignals: true,
+          status: "ok"
+        };
+      },
+      // eslint-disable-next-line @typescript-eslint/require-await -- Interface requires async
+      async check() {
+        return NEEDS_APPLY;
+      },
+      local: true,
+      name: moduleName
+    };
+  }
+};
+async function applyConditionalModules(parameters) {
+  const { dryRun = false, modules, ssh: ssh2 } = parameters;
+  let state = createConditionalApplyState(parameters.environment);
+  for (const currentModule of modules) {
+    const checkResult = await currentModule.check(ssh2, state.environment);
+    if (checkResult === "ok") continue;
+    if (!shouldExecuteConditionalApply(currentModule, dryRun)) {
+      state = markConditionalApplyChanged(state);
+      continue;
+    }
+    const result = await executeConditionalApply({
+      dryRun,
+      environment: state.environment,
+      module: currentModule,
+      ssh: ssh2
+    });
+    if (result.status === "failed") return result;
+    state = await mergeConditionalApplyState(state, result);
+    if (state.stopRun === true) break;
+  }
+  return {
+    _flushSignals: state.flushSignals,
+    _stopRun: state.stopRun,
+    meta: state.meta.length === 0 ? void 0 : state.meta,
+    status: state.status
+  };
+}
+function shouldExecuteConditionalApply(module, dryRun) {
+  if (!dryRun) return true;
+  return module._applyDryRun != null || module._dryRunBlocker === true || module._dryRunMetaProducer === true;
+}
+function createConditionalApplyState(environment) {
+  return { environment: { ...environment }, meta: [], status: "ok" };
+}
+function markConditionalApplyChanged(state) {
+  return { ...state, status: "changed" };
+}
+async function executeConditionalApply(parameters) {
+  const { dryRun, environment, module, ssh: ssh2 } = parameters;
+  if (dryRun && module._applyDryRun != null) {
+    return module._applyDryRun(ssh2, environment);
+  }
+  return module.apply(ssh2, environment);
+}
+function whenNeedsDryRunApply(modules) {
+  return modules.some((module) => shouldExecuteConditionalDryRun(module));
+}
+function shouldExecuteConditionalDryRun(module) {
+  return module._applyDryRun != null || module._dryRunBlocker === true || module._dryRunMetaProducer === true;
+}
+async function mergeConditionalApplyState(state, result) {
+  const environment = await mergeEnvironmentFromMeta(state.environment, result.meta);
+  return {
+    environment,
+    flushSignals: result._flushSignals === true ? true : state.flushSignals,
+    meta: result.meta == null ? state.meta : [...state.meta, ...result.meta],
+    status: result.status === "changed" ? "changed" : state.status,
+    stopRun: result._stopRun === true ? true : state.stopRun
+  };
+}
+function createWhenDryRunApply(condition, modules, needsDryRunApply) {
+  if (!needsDryRunApply) return void 0;
+  return async (ssh2, environment) => {
+    if (!condition(environment)) {
+      return { status: "skipped" };
+    }
+    return applyConditionalModules({ dryRun: true, environment, modules, ssh: ssh2 });
+  };
+}
+function when(condition, ...modules) {
+  const needsDryRunApply = whenNeedsDryRunApply(modules);
+  const applyDryRun = createWhenDryRunApply(condition, modules, needsDryRunApply);
+  return {
+    ...modules.some((module) => module._dryRunBlocker === true) ? { _dryRunBlocker: true } : {},
+    ...modules.some((module) => module._dryRunMetaProducer === true) ? { _dryRunMetaProducer: true } : {},
+    ...applyDryRun == null ? {} : { _applyDryRun: applyDryRun },
+    async apply(ssh2, environment) {
+      if (!condition(environment)) {
+        return { status: "skipped" };
+      }
+      return applyConditionalModules({ environment, modules, ssh: ssh2 });
+    },
+    async check(ssh2, environment) {
+      if (!condition(environment)) {
+        return "ok";
+      }
+      const currentEnvironment = { ...environment };
+      for (const currentModule of modules) {
+        const result = await currentModule.check(ssh2, currentEnvironment);
+        if (result === NEEDS_APPLY) {
+          return NEEDS_APPLY;
+        }
+      }
+      return "ok";
+    },
+    name: `when: conditional (${modules.length} modules)`
+  };
+}
+
+// src/recipe.ts
+var INTERRUPTED_BEFORE_APPLY = /* @__PURE__ */ Symbol("recipe-interrupted-before-apply");
+function applyRecipeStepToState(state, step, preserveControlPlaneMeta) {
+  let stepMeta;
+  if (step.meta == null) {
+    stepMeta = void 0;
+  } else if (preserveControlPlaneMeta) {
+    stepMeta = step.meta;
+  } else {
+    stepMeta = step.meta.filter(isEnvironmentMetaEntry);
+  }
+  const nextMeta = stepMeta == null ? state.meta ?? [] : [...state.meta ?? [], ...stepMeta];
+  let nextStatus = state.status;
+  if (step.status === "failed") nextStatus = "failed";
+  else if (step.status === "changed") nextStatus = "changed";
+  return {
+    env: step.env,
+    meta: nextMeta,
+    signalsPending: step.status === "changed" ? true : state.signalsPending,
+    status: nextStatus,
+    stopRun: step._stopRun === true ? true : state.stopRun
+  };
+}
+async function executeOneModule(parameters) {
+  const { currentEnvironment, ssh: ssh2, targetModule } = parameters;
+  const verbose = parameters.verbose ?? false;
+  const connection = targetModule.local === true ? null : ssh2;
+  const checkResult = await checkRecipeChild(targetModule, connection, currentEnvironment);
+  if (checkResult === "ok") {
+    printModuleResult(targetModule.name, "ok");
+    return null;
+  }
+  if ((parameters.shutdownSignal?.() ?? null) != null) {
+    return INTERRUPTED_BEFORE_APPLY;
+  }
+  const result = await targetModule.apply(connection, currentEnvironment);
+  printModuleResult(targetModule.name, result.status);
+  if (result.status === "failed" && result.error != null) {
+    printCommandFailure(result.error, verbose);
+  }
+  const environment = await mergeEnvironmentFromMeta(currentEnvironment, result.meta);
+  return {
+    _flushSignals: result._flushSignals,
+    _stopRun: result._stopRun,
+    env: environment,
+    meta: result.meta,
+    status: result.status
+  };
+}
+async function checkRecipeChild(targetModule, connection, currentEnvironment) {
+  startModuleSpinner(targetModule.name);
+  return targetModule.check(connection, currentEnvironment);
+}
+async function applyExecutedRecipeStep(parameters) {
+  if (parameters.step == null) return parameters.state;
+  if (parameters.step === INTERRUPTED_BEFORE_APPLY) return null;
+  if (parameters.onChildStep != null) {
+    await parameters.onChildStep(parameters.step);
+  }
+  return applyRecipeStepToState(
+    parameters.state,
+    parameters.step,
+    parameters.preserveControlPlaneMeta
+  );
+}
+function failedRecipeState(environment) {
+  return {
+    env: environment,
+    meta: void 0,
+    signalsPending: false,
+    status: "failed"
+  };
+}
+function annotateRecipeChildError(moduleName, error) {
+  const prefix = `[${moduleName}] `;
+  if (error instanceof CommandError) {
+    return new CommandError(`${prefix}${error.message}`, error.fullStdout, error.fullStderr);
+  }
+  if (error instanceof Error) {
+    return new Error(`${prefix}${error.message}`);
+  }
+  return new Error(`${prefix}${String(error)}`);
+}
+async function executeRecipeChildStep(parameters) {
+  try {
+    return { kind: "step", step: await executeOneModule(parameters) };
+  } catch (error) {
+    if (parameters.shutdownSignal() != null) {
+      return { kind: "step", step: INTERRUPTED_BEFORE_APPLY };
+    }
+    printModuleResult(parameters.targetModule.name, "failed");
+    printCommandFailure(error, parameters.verbose);
+    return { kind: "failed", state: failedRecipeState(parameters.currentEnvironment) };
+  }
+}
+async function processRecipeStep(parameters) {
+  if (parameters.step.kind === "failed") {
+    return { kind: "break", state: parameters.step.state };
+  }
+  const nextState = await applyExecutedRecipeStep({
+    onChildStep: parameters.onChildStep,
+    preserveControlPlaneMeta: parameters.preserveControlPlaneMeta,
+    state: parameters.state,
+    step: parameters.step.step
+  });
+  if (nextState == null) {
+    return { kind: "break", state: parameters.state };
+  }
+  let state = nextState;
+  if (shouldFlushRecipeSignals(parameters.step.step, state, parameters.signals)) {
+    const signalStatus = await flushPendingRecipeSignals({
+      environment: state.env,
+      onSignalStep: parameters.onSignalStep,
+      shutdownSignal: parameters.shutdownSignal,
+      signalHooks: parameters.signalHooks,
+      signals: parameters.signals,
+      ssh: parameters.ssh,
+      verbose: parameters.verbose
+    });
+    state = applyRecipeSignalStatus(state, signalStatus);
+  }
+  if (state.status === "failed" || state.stopRun === true) {
+    return { kind: "break", state };
+  }
+  return { kind: "continue", state };
+}
+async function executeModules(modules, ssh2, parameters) {
+  const onChildStep = parameters.onChildStep;
+  const preserveControlPlaneMeta = onChildStep == null;
+  const shutdownSignal = parameters.shutdownSignal ?? (() => null);
+  const verbose = parameters.verbose ?? false;
+  let state = {
+    env: { ...parameters.environment },
+    meta: void 0,
+    signalsPending: false,
+    status: "ok"
+  };
+  for (const currentModule of modules) {
+    if (shutdownSignal() != null) break;
+    const step = await executeRecipeChildStep({
+      currentEnvironment: state.env,
+      shutdownSignal,
+      ssh: ssh2,
+      targetModule: currentModule,
+      verbose
+    });
+    const processedStep = await processRecipeStep({
+      onChildStep,
+      onSignalStep: parameters.onSignalStep,
+      preserveControlPlaneMeta,
+      shutdownSignal,
+      signalHooks: parameters.signalHooks,
+      signals: parameters.signals,
+      ssh: ssh2,
+      state,
+      step,
+      verbose
+    });
+    state = processedStep.state;
+    if (processedStep.kind === "break") return state;
+  }
+  return state;
+}
+async function triggerSignals(parameters) {
+  return runSignalModules({
+    environment: parameters.environment,
+    hooks: parameters.signalHooks,
+    onSignalStep: parameters.onSignalStep,
+    shutdownSignal: parameters.shutdownSignal,
+    signals: parameters.signals,
+    ssh: parameters.ssh,
+    verbose: parameters.verbose
+  });
+}
+function shouldFlushRecipeSignals(step, state, signals2) {
+  return step != null && step !== INTERRUPTED_BEFORE_APPLY && step._flushSignals === true && state.signalsPending && signals2 != null;
+}
+function applyRecipeSignalStatus(state, signalStatus) {
+  return {
+    ...state,
+    signalsPending: false,
+    status: signalStatus === "failed" ? "failed" : state.status
+  };
+}
+async function flushPendingRecipeSignals(parameters) {
+  return triggerSignals(parameters);
+}
+async function applyRecipe(parameters) {
+  return withRecipeOutputScope(async () => {
+    const shutdownSignal = parameters.options?.shutdownSignal;
+    const verbose = parameters.options?.verbose ?? false;
+    printRecipeHeader(parameters.name);
+    const state = await executeModules(parameters.modules, parameters.ssh, {
+      environment: parameters.environment,
+      onChildStep: parameters.options?.onChildStep,
+      onSignalStep: parameters.options?.onSignalStep,
+      shutdownSignal,
+      signalHooks: parameters.options?.signalHooks,
+      signals: parameters.signals,
+      verbose
+    });
+    if (shouldRunRecipeSignalsAtEnd(state, parameters.signals)) {
+      state.status = await triggerSignals({
+        environment: state.env,
+        onSignalStep: parameters.options?.onSignalStep,
+        shutdownSignal,
+        signalHooks: parameters.options?.signalHooks,
+        signals: parameters.signals,
+        ssh: parameters.ssh,
+        verbose
+      });
+    }
+    return {
+      _stopRun: state.stopRun,
+      meta: state.meta,
+      status: state.status
+    };
+  });
+}
+function shouldRunRecipeSignalsAtEnd(state, signals2) {
+  return state.signalsPending && state.status === "changed" && signals2 != null;
+}
+function recipe(name, modules, options) {
+  return {
+    _isRecipe: true,
+    _modules: modules,
+    _signals: options?.signals,
+    async apply(ssh2, environment, parameters) {
+      return applyRecipe({
+        environment,
+        modules,
+        name,
+        options: parameters,
+        signals: options?.signals,
+        ssh: ssh2
+      });
+    },
+    async check(ssh2, environment) {
+      for (const childModule of modules) {
+        const connection = childModule.local === true ? null : ssh2;
+        let result;
+        try {
+          result = await childModule.check(connection, environment);
+        } catch (error) {
+          throw annotateRecipeChildError(childModule.name, error);
+        }
+        if (result === NEEDS_APPLY) return NEEDS_APPLY;
+      }
+      return "ok";
+    },
+    name
+  };
+}
+
+// src/server.ts
+function server(config) {
+  if (config.host.length === 0) {
+    throw new Error("ServerDefinition: host is required");
+  }
+  if (config.name.length === 0) {
+    throw new Error("ServerDefinition: name is required");
+  }
+  validateSshConfig(config.ssh);
+  if (config.run.length === 0) {
+    throw new Error("ServerDefinition: run must contain at least one module");
+  }
+  return config;
+}
+export {
+  NEEDS_APPLY,
+  apt,
+  archive,
+  assert,
+  assertValidModuleMetaEntries,
+  assertValidModuleMetaEntry,
+  command,
+  compose,
+  cron,
+  debug,
+  diffEnvironmentToMetaEntries,
+  download,
+  environmentMeta,
+  environmentToMetaEntries,
+  fail,
+  failed,
+  failedCommand,
+  file,
+  firstRun,
+  git,
+  group,
+  hostname,
+  isBooleanEnvironmentMetaEntry,
+  isEnvironmentMetaEntry,
+  isLazyEnvironmentMetaEntry,
+  isNumberEnvironmentMetaEntry,
+  isSshdPortMetaEntry,
+  isStringEnvironmentMetaEntry,
+  isSystemHostMetaEntry,
+  isSystemRebootMetaEntry,
+  mergeEnvironmentFromMeta,
+  meta,
+  mount,
+  net,
+  op,
+  pkg as package,
+  pause,
+  recipe,
+  releaseUpgrade,
+  rsync,
+  script,
+  server,
+  service,
+  shellQuote,
+  signals,
+  ssh,
+  sshd,
+  sshdPortMeta,
+  sysctl,
+  system,
+  systemHostMeta,
+  systemRebootMeta,
+  systemd,
+  ufw,
+  user,
+  when
+};
+//# sourceMappingURL=index.js.map