@sshkeda/task 0.0.0-stage → 1.0.0

package/src/shared/process-errors.ts

@@ -0,0 +1,191 @@
+import { Schema } from "effect";
+
+import { TASK_ERROR_FIELDS, UNATTRIBUTED_FAILURE_FIELDS } from "./error-fields.ts";
+import { describeCauseMessage } from "./report-errors.ts";
+
+export class ProcDirectoryUnlistable extends Schema.TaggedError<ProcDirectoryUnlistable>()(
+  "ProcDirectoryUnlistable",
+  {
+    ...TASK_ERROR_FIELDS,
+    taskName: Schema.NullOr(Schema.String),
+    directoryPath: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  public override get message() {
+    return `could not list ${this.directoryPath} to find leftover processes because ${describeCauseMessage(this.cause)}`;
+  }
+}
+
+export class ProcStatUnreadable extends Schema.TaggedError<ProcStatUnreadable>()(
+  "ProcStatUnreadable",
+  {
+    ...TASK_ERROR_FIELDS,
+    taskName: Schema.NullOr(Schema.String),
+    filePath: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  public override get message() {
+    return `could not be read to find leftover processes because ${describeCauseMessage(this.cause)}`;
+  }
+}
+
+export class ProcStatMalformed extends Schema.TaggedError<ProcStatMalformed>()(
+  "ProcStatMalformed",
+  {
+    ...TASK_ERROR_FIELDS,
+    taskName: Schema.NullOr(Schema.String),
+    filePath: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  public override get message() {
+    return `has no readable state, parent, group and start time because ${describeCauseMessage(this.cause)}`;
+  }
+}
+
+export class ProcCommandLineUnreadable extends Schema.TaggedError<ProcCommandLineUnreadable>()(
+  "ProcCommandLineUnreadable",
+  {
+    ...TASK_ERROR_FIELDS,
+    taskName: Schema.NullOr(Schema.String),
+    filePath: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  public override get message() {
+    return `could not be read because ${describeCauseMessage(this.cause)}`;
+  }
+}
+
+export class ProcRunMarkerUnreadable extends Schema.TaggedError<ProcRunMarkerUnreadable>()(
+  "ProcRunMarkerUnreadable",
+  {
+    ...TASK_ERROR_FIELDS,
+    taskName: Schema.NullOr(Schema.String),
+    filePath: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  public override get message() {
+    return `could not be read because ${describeCauseMessage(this.cause)}`;
+  }
+}
+
+export class ProcessNotSignaled extends Schema.TaggedError<ProcessNotSignaled>()(
+  "ProcessNotSignaled",
+  {
+    ...TASK_ERROR_FIELDS,
+    taskName: Schema.NullOr(Schema.String),
+    processId: Schema.Int,
+    signal: Schema.Literals(["SIGKILL", "SIGSTOP", "SIGCONT", 0]),
+    cause: Schema.Defect(),
+  },
+) {
+  public override get message() {
+    return `could not send ${this.signal === 0 ? "a liveness check" : this.signal} to ${this.processId < 0 ? `process group ${-this.processId}` : `process ${this.processId}`} because ${describeCauseMessage(this.cause)}`;
+  }
+}
+
+export class SystemLibraryNotLoaded extends Schema.TaggedError<SystemLibraryNotLoaded>()(
+  "SystemLibraryNotLoaded",
+  {
+    ...TASK_ERROR_FIELDS,
+    taskName: Schema.NullOr(Schema.String),
+    libraryPath: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  public override get message() {
+    return `could not load ${this.libraryPath} to list processes because ${describeCauseMessage(this.cause)}`;
+  }
+}
+
+export class ProcessArgumentsMalformed extends Schema.TaggedError<ProcessArgumentsMalformed>()(
+  "ProcessArgumentsMalformed",
+  {
+    ...TASK_ERROR_FIELDS,
+    processId: Schema.Int,
+    argumentCount: Schema.Int,
+    argumentsFound: Schema.Int,
+  },
+) {
+  public override get message() {
+    return `kern.procargs2 for process ${this.processId} declares ${this.argumentCount} arguments but holds ${this.argumentsFound} NUL-terminated strings after its executable path`;
+  }
+}
+
+export class SystemCallFailed extends Schema.TaggedError<SystemCallFailed>()("SystemCallFailed", {
+  ...TASK_ERROR_FIELDS,
+  call: Schema.String,
+  processId: Schema.NullOr(Schema.Int),
+  errorNumber: Schema.Int,
+  errorName: Schema.String,
+}) {
+  public override get message() {
+    return `${this.call}${this.processId === null ? "" : ` for process ${this.processId}`} failed with ${this.errorName} (errno ${this.errorNumber})`;
+  }
+}
+
+export class ProcessCommandLineNotRead extends Schema.TaggedError<ProcessCommandLineNotRead>()(
+  "ProcessCommandLineNotRead",
+  {
+    ...TASK_ERROR_FIELDS,
+    taskName: Schema.NullOr(Schema.String),
+    processId: Schema.Int,
+    cause: Schema.Union([SystemCallFailed, ProcessArgumentsMalformed]),
+  },
+) {
+  public override get message() {
+    return `could not read the command line of leftover process ${this.processId} because ${this.cause.message}`;
+  }
+}
+
+export class ProcessTableNotRead extends Schema.TaggedError<ProcessTableNotRead>()(
+  "ProcessTableNotRead",
+  {
+    ...TASK_ERROR_FIELDS,
+    taskName: Schema.NullOr(Schema.String),
+    cause: Schema.Union([SystemCallFailed, ProcessArgumentsMalformed]),
+  },
+) {
+  public override get message() {
+    return `could not read the process table to find leftover processes because ${this.cause.message}`;
+  }
+}
+
+export const UncaughtWorkerError = Schema.Struct({
+  message: Schema.String,
+  location: Schema.NullOr(Schema.String),
+});
+
+export class WorkerExited extends Schema.TaggedError<WorkerExited>()("WorkerExited", {
+  ...TASK_ERROR_FIELDS,
+  taskName: Schema.NullOr(Schema.String),
+  workerId: Schema.Int,
+  exitCode: Schema.Int,
+  uncaughtError: Schema.NullOr(UncaughtWorkerError),
+}) {
+  public get location() {
+    return this.uncaughtError?.location ?? undefined;
+  }
+  public override get message() {
+    const howItStopped =
+      this.uncaughtError === null
+        ? `exited on its own with code ${this.exitCode}`
+        : `stopped on the uncaught error ${this.uncaughtError.message}`;
+    return this.taskName === null
+      ? `worker ${this.workerId} ${howItStopped}`
+      : `its worker ${howItStopped}`;
+  }
+}
+
+export class SupervisorSocketNotOpened extends Schema.TaggedError<SupervisorSocketNotOpened>()(
+  "SupervisorSocketNotOpened",
+  { ...TASK_ERROR_FIELDS, ...UNATTRIBUTED_FAILURE_FIELDS, cause: Schema.Defect() },
+) {
+  public override get message() {
+    return `could not open the socket the run reports to its supervisor on because ${describeCauseMessage(this.cause)}`;
+  }
+}

package/src/shared/read-environment-config.ts

@@ -0,0 +1,239 @@
+import {
+  Array as Arrays,
+  Effect,
+  Config,
+  ConfigProvider,
+  Duration,
+  Option,
+  Path,
+  Schema,
+} from "effect";
+
+import {
+  BunVersionUnsupported,
+  HomeDirectoryPathMissing,
+  SetupLimitInvalid,
+  StateDirectoryPathBlank,
+  WorkerCountAboveMaximum,
+  WorkerCountInvalid,
+} from "./environment-config-errors.ts";
+import { dieOnInvariantFailure } from "./invariant-errors.ts";
+import { markRuntimeConfigProvider } from "./name-config-key.ts";
+import { TASK_STATE_DIRECTORY_NAME, packageNameParts } from "./names-from-package-json.ts";
+import { TASK_PACKAGE } from "./task-package.ts";
+
+const TASK_ENVIRONMENT_VARIABLE_PREFIX = packageNameParts.join("_").toUpperCase();
+
+export const availableParallelism = Effect.sync(() => navigator.hardwareConcurrency);
+
+export const MAXIMUM_WORKER_COUNT = 1024;
+
+export const workingDirectoryPath = Effect.sync(() => process.cwd());
+
+const FIRST_SCRIPT_ARGUMENT_INDEX = 2;
+
+export const commandLineArguments = Effect.sync(() =>
+  process.argv.slice(FIRST_SCRIPT_ARGUMENT_INDEX),
+);
+
+export const bunArguments = Effect.sync(() => [...process.execArgv]);
+
+const BUN_WATCH_MODE_FLAGS = ["--watch", "--hot"] as const;
+
+export const bunWatchModeFlag = Effect.sync(() =>
+  Option.fromUndefinedOr(BUN_WATCH_MODE_FLAGS.find((flag) => process.execArgv.includes(flag))),
+);
+
+const isWorkingDirectoryFlag = (flag: string) => flag === "--cwd" || flag.startsWith("--cwd=");
+
+const SUPERVISOR_SOCKET_ARGUMENT_PREFIX = `--${packageNameParts.join("-")}-supervisor-socket=`;
+
+export const supervisedRunCommand = (preloadFlag: string, supervisorSocketPath: string) =>
+  Effect.sync(() => [
+    process.execPath,
+    preloadFlag,
+    ...process.execArgv,
+    ...(process.execArgv.some((flag) => isWorkingDirectoryFlag(flag))
+      ? [`--cwd=${process.cwd()}`]
+      : []),
+    ...process.argv.slice(1, FIRST_SCRIPT_ARGUMENT_INDEX),
+    `${SUPERVISOR_SOCKET_ARGUMENT_PREFIX}${supervisorSocketPath}`,
+    ...process.argv.slice(FIRST_SCRIPT_ARGUMENT_INDEX),
+  ]);
+
+export const takeSupervisorSocketPath = Effect.sync(() => {
+  const supervisorSocketArgument = process.argv[FIRST_SCRIPT_ARGUMENT_INDEX] ?? "";
+  if (!supervisorSocketArgument.startsWith(SUPERVISOR_SOCKET_ARGUMENT_PREFIX)) {
+    return Option.none();
+  }
+  process.argv.splice(FIRST_SCRIPT_ARGUMENT_INDEX, 1);
+  return Option.some(supervisorSocketArgument.slice(SUPERVISOR_SOCKET_ARGUMENT_PREFIX.length));
+});
+
+const NON_BLANK_TEXT = Schema.String.check(Schema.isPattern(/\S/u));
+
+const readEnvironmentKeepingEmptyValues = () =>
+  ConfigProvider.fromEnv({ preserveEmptyStrings: true });
+
+const taskOwnConfigProvider = readEnvironmentKeepingEmptyValues();
+
+export const runtimeConfigProviderLayer = ConfigProvider.layer(
+  Effect.sync(() => markRuntimeConfigProvider(readEnvironmentKeepingEmptyValues())),
+);
+
+const STATE_DIRECTORY_VARIABLE_NAME = `${TASK_ENVIRONMENT_VARIABLE_PREFIX}_STATE_DIRECTORY`;
+
+const WORKER_COUNT_VARIABLE_NAME = `${TASK_ENVIRONMENT_VARIABLE_PREFIX}_WORKERS`;
+
+const readEnvironmentVariable = (variableName: string) =>
+  Config.String(variableName)
+    .pipe(Config.option)
+    .parse(taskOwnConfigProvider)
+    .pipe(
+      dieOnInvariantFailure(
+        "configuration",
+        `the environment provides ${variableName} or omits it`,
+      ),
+    );
+
+const readEnvironmentVariableNow = (variableName: string) =>
+  Effect.suspend(() =>
+    Config.String(variableName).pipe(Config.option).parse(readEnvironmentKeepingEmptyValues()),
+  ).pipe(
+    dieOnInvariantFailure("configuration", `the environment provides ${variableName} or omits it`),
+  );
+
+const isNonBlankText = Schema.is(NON_BLANK_TEXT);
+
+const isWholeDecimalNumberAboveZero = Schema.is(
+  Schema.String.check(Schema.isPattern(/^0*[1-9]\d*$/u)),
+);
+
+export const readStateDirectory = Effect.fn("readStateDirectory")(function* () {
+  const path = yield* Path.Path;
+  const configuredStateDirectoryPath = yield* readEnvironmentVariable(
+    STATE_DIRECTORY_VARIABLE_NAME,
+  );
+  if (Option.isSome(configuredStateDirectoryPath)) {
+    if (!isNonBlankText(configuredStateDirectoryPath.value)) {
+      return yield* new StateDirectoryPathBlank({
+        variableName: STATE_DIRECTORY_VARIABLE_NAME,
+        value: configuredStateDirectoryPath.value,
+      });
+    }
+    const stateDirectoryPath = path.resolve(configuredStateDirectoryPath.value);
+    return { stateDirectoryPath, configuredStateDirectoryPath: stateDirectoryPath };
+  }
+  const homeDirectoryPath = yield* readEnvironmentVariable("HOME");
+  const isHomeDirectoryPathMissing =
+    Option.isNone(homeDirectoryPath) || !isNonBlankText(homeDirectoryPath.value);
+  if (isHomeDirectoryPathMissing) {
+    return yield* new HomeDirectoryPathMissing({
+      stateDirectoryVariableName: STATE_DIRECTORY_VARIABLE_NAME,
+      homeValue: Option.getOrNull(homeDirectoryPath),
+    });
+  }
+  return {
+    stateDirectoryPath: path.resolve(path.join(homeDirectoryPath.value, TASK_STATE_DIRECTORY_NAME)),
+    configuredStateDirectoryPath: null,
+  };
+});
+
+export const readWorkerCount = Effect.fn("readWorkerCount")(function* () {
+  const configuredWorkerCount = yield* readEnvironmentVariable(WORKER_COUNT_VARIABLE_NAME);
+  if (Option.isNone(configuredWorkerCount)) {
+    return yield* availableParallelism;
+  }
+  if (!isWholeDecimalNumberAboveZero(configuredWorkerCount.value)) {
+    return yield* new WorkerCountInvalid({
+      variableName: WORKER_COUNT_VARIABLE_NAME,
+      value: configuredWorkerCount.value,
+    });
+  }
+  const workerCount = Number(configuredWorkerCount.value);
+  if (workerCount > MAXIMUM_WORKER_COUNT) {
+    return yield* new WorkerCountAboveMaximum({
+      variableName: WORKER_COUNT_VARIABLE_NAME,
+      value: configuredWorkerCount.value,
+      maximum: MAXIMUM_WORKER_COUNT,
+    });
+  }
+  return workerCount;
+});
+
+const SETUP_LIMIT_VARIABLE_NAME = `${TASK_ENVIRONMENT_VARIABLE_PREFIX}_SETUP_LIMIT`;
+
+const DEFAULT_SETUP_LIMIT = Duration.minutes(1);
+
+const decodeDurationOption = Schema.decodeUnknownOption(Schema.DurationFromString);
+
+export const readSetupLimit = Effect.fn("readSetupLimit")(function* () {
+  const configuredSetupLimit = yield* readEnvironmentVariable(SETUP_LIMIT_VARIABLE_NAME);
+  if (Option.isNone(configuredSetupLimit)) {
+    return DEFAULT_SETUP_LIMIT;
+  }
+  const setupLimit = decodeDurationOption(configuredSetupLimit.value);
+  const isFiniteDurationAboveZero =
+    Option.isSome(setupLimit) &&
+    Duration.isFinite(setupLimit.value) &&
+    Duration.isGreaterThan(setupLimit.value, Duration.zero);
+  if (!isFiniteDurationAboveZero) {
+    return yield* new SetupLimitInvalid({
+      variableName: SETUP_LIMIT_VARIABLE_NAME,
+      value: configuredSetupLimit.value,
+    });
+  }
+  return setupLimit.value;
+});
+
+export const inheritedEnvironment = Effect.sync(() => ({ ...process.env }));
+
+export const RUN_MARKERS_VARIABLE_NAME = `${TASK_ENVIRONMENT_VARIABLE_PREFIX}_RUN_MARKERS`;
+
+export const inheritedRunMarkers = readEnvironmentVariableNow(RUN_MARKERS_VARIABLE_NAME).pipe(
+  Effect.map((runMarkers) =>
+    Option.getOrElse(runMarkers, () => "")
+      .split(" ")
+      .filter((token) => token !== ""),
+  ),
+);
+
+const VARIABLES_EVERY_COMMAND_SEES = ["HOME", "PATH", "TMPDIR"] as const;
+
+const TASK_CONFIG_EVERY_COMMAND_SEES = [
+  STATE_DIRECTORY_VARIABLE_NAME,
+  WORKER_COUNT_VARIABLE_NAME,
+  SETUP_LIMIT_VARIABLE_NAME,
+] as const;
+
+export const environmentEveryCommandSees = Effect.forEach(
+  [...VARIABLES_EVERY_COMMAND_SEES, ...TASK_CONFIG_EVERY_COMMAND_SEES],
+  (variableName) =>
+    readEnvironmentVariableNow(variableName).pipe(
+      Effect.map((value) =>
+        Option.map(value, (presentValue) => [variableName, presentValue] as const),
+      ),
+    ),
+).pipe(Effect.map((entries) => Object.fromEntries(Arrays.getSomes(entries))));
+
+export const passStateDirectoryToCommands = (configuredStateDirectoryPath: string | null) =>
+  Effect.sync(() => {
+    if (configuredStateDirectoryPath !== null) {
+      process.env[STATE_DIRECTORY_VARIABLE_NAME] = configuredStateDirectoryPath;
+    }
+  });
+
+export const requireSupportedBunVersion = (
+  bunVersion: string,
+  supportedRange: string = TASK_PACKAGE.engines.bun,
+) =>
+  Bun.semver.satisfies(bunVersion.replace(/[-+].*$/u, ""), supportedRange)
+    ? Effect.void
+    : Effect.fail(
+        new BunVersionUnsupported({
+          bunVersion,
+          supportedRange,
+          taskPackageName: TASK_PACKAGE.name,
+          taskVersion: TASK_PACKAGE.version,
+        }),
+      );

package/src/shared/record-tasks-made.ts

@@ -0,0 +1,10 @@
+import type { Task } from "../lib/task/index.ts";
+
+const tasksMadeByName = new Map<string, Task[]>();
+
+export const recordTaskMade = (madeTask: Task) => {
+  tasksMadeByName.set(madeTask.name, [...(tasksMadeByName.get(madeTask.name) ?? []), madeTask]);
+};
+
+export const findTasksMadeWithName = (taskName: string): readonly Task[] =>
+  tasksMadeByName.get(taskName) ?? [];

package/src/shared/report-cause.ts

@@ -0,0 +1,140 @@
+import { Array as Arrays, Cause, Formatter, Option, Predicate, Result, Schema } from "effect";
+
+import { PrintableError } from "../lib/errors/index.ts";
+import { CommandRefusal } from "./command-errors.ts";
+import { findUserLocationInStack } from "./find-user-locations-in-stack-traces.ts";
+import {
+  CauseWithoutFailure,
+  describeCauseMessage,
+  ErrorStack,
+  reportError,
+  TaskRaisedError,
+  UntaggedFailure,
+} from "./report-errors.ts";
+import { failureValuesOfReason } from "./select-cause-reasons.ts";
+import { TASK_PACKAGE } from "./task-package.ts";
+
+const TaskRaisedContainer = Schema.Struct({
+  raisedBy: Schema.Literal(TASK_PACKAGE.name),
+  reportedErrors: Schema.NonEmptyArray(PrintableError),
+});
+
+const UserError = Schema.Struct({ name: Schema.String, message: Schema.String });
+
+const UNTAGGED_ERROR_NAMES = new Set(["", "Error"]);
+
+const ErrorFields = Schema.Record(Schema.String, Schema.Unknown);
+
+const userTagOf = (failureValue: unknown) =>
+  Option.flatMap(Schema.decodeUnknownOption(ErrorFields)(failureValue), ({ _tag }) =>
+    Option.liftPredicate(_tag, Predicate.isString),
+  );
+
+const ErrorCausedByCommandRefusal = Schema.Struct({ cause: CommandRefusal });
+
+const ENGINE_ERROR_NAMES = new Set(["TypeError", "ReferenceError"]);
+
+const ENGINE_SOURCE_EXCERPT =
+  /^(?<statement>[\s\S]*?) \(In '[\s\S]*'(?:, (?<valueNote>'[\s\S]*' is [\s\S]*))?\)$/u;
+
+const withoutEngineSourceExcerpt = (errorName: string, defectMessage: string) => {
+  const [, statement, valueNote] = ENGINE_ERROR_NAMES.has(errorName)
+    ? (ENGINE_SOURCE_EXCERPT.exec(defectMessage) ?? [])
+    : [];
+  if (statement === undefined) {
+    return defectMessage;
+  }
+  return valueNote === undefined ? statement : `${statement} (${valueNote})`;
+};
+
+const reportReason = (
+  reason: Cause.Reason<unknown>,
+  foreignMessagePrefix: string,
+): readonly PrintableError[] => {
+  if (Cause.isInterruptReason(reason)) {
+    return [];
+  }
+  const [failureValue] = failureValuesOfReason(reason);
+  const stackLocation = Option.flatMap(
+    Schema.decodeUnknownOption(ErrorStack)(failureValue),
+    (withStack) => Option.fromUndefinedOr(findUserLocationInStack(withStack.stack)),
+  );
+  const userLocation = Option.match(stackLocation, {
+    onSome: (location) => ({ location }),
+    onNone: () => ({}),
+  });
+  return Option.match(Schema.decodeUnknownOption(TaskRaisedContainer)(failureValue), {
+    onSome: (container) => container.reportedErrors,
+    onNone: () =>
+      Option.match(Schema.decodeUnknownOption(ErrorCausedByCommandRefusal)(failureValue), {
+        onSome: (causedByRefusal) => [reportError(causedByRefusal.cause)],
+        onNone: () =>
+          Option.match(Schema.decodeUnknownOption(TaskRaisedError)(failureValue), {
+            onSome: (taskRaised) => [reportError(taskRaised)],
+            onNone: () =>
+              Option.match(
+                Option.filter(
+                  Schema.decodeUnknownOption(UserError)(failureValue),
+                  (userError) =>
+                    Option.isSome(userTagOf(failureValue)) ||
+                    !UNTAGGED_ERROR_NAMES.has(userError.name),
+                ),
+                {
+                  onSome: (userError) => {
+                    const tag = Option.getOrElse(userTagOf(failureValue), () => userError.name);
+                    const message = Cause.isDieReason(reason)
+                      ? withoutEngineSourceExcerpt(userError.name, userError.message)
+                      : userError.message;
+                    return [
+                      {
+                        tag,
+                        message: `${foreignMessagePrefix}${message === "" ? tag : message}`,
+                        ...userLocation,
+                      },
+                    ];
+                  },
+                  onNone: () => [
+                    reportError(
+                      new UntaggedFailure({
+                        failureMessage: `${foreignMessagePrefix}${describeCauseMessage(failureValue)}`,
+                        ...userLocation,
+                      }),
+                    ),
+                  ],
+                },
+              ),
+          }),
+      }),
+  });
+};
+
+const isRangeError = Schema.is(Schema.instanceOf(RangeError));
+
+export const causeWithPrintableErrors = <Failure>(cause: Cause.Cause<Failure>) =>
+  Result.getOrElse(
+    Result.try(() => {
+      Cause.pretty(cause);
+      return cause;
+    }),
+    (formattingFailure) => {
+      if (!isRangeError(formattingFailure)) {
+        throw formattingFailure;
+      }
+      return Cause.die(
+        new Error(Formatter.format({ cause, formattingFailure }, { ignoreToString: true })),
+      );
+    },
+  );
+
+export const reportCause = <Failure>(cause: Cause.Cause<Failure>, foreignMessagePrefix = "") => {
+  const details = Cause.pretty(causeWithPrintableErrors(cause));
+  const reportedErrors = cause.reasons.flatMap((reason) =>
+    reportReason(reason, foreignMessagePrefix),
+  );
+  return {
+    failures: Arrays.isArrayNonEmpty(reportedErrors)
+      ? reportedErrors
+      : Arrays.of(reportError(new CauseWithoutFailure({ details }))),
+    details,
+  };
+};

package/src/shared/report-errors.ts

@@ -0,0 +1,121 @@
+import { Formatter, Option, PlatformError, Predicate, Schema, SchemaTransformation } from "effect";
+
+import type { PrintableError } from "../lib/errors/index.ts";
+import { cutToGraphemes } from "./cut-to-graphemes.ts";
+import { TASK_ERROR_FIELDS } from "./error-fields.ts";
+import { TASK_PACKAGE } from "./task-package.ts";
+
+export const withLocationOrElse = (printable: PrintableError, fallbackLocation: string) => {
+  const { location, ...printableWithoutLocation } = printable;
+  return { ...printableWithoutLocation, location: location ?? fallbackLocation };
+};
+
+export const ErrorStack = Schema.Struct({ stack: Schema.String });
+
+export const TaskRaisedError = Schema.Struct({
+  raisedBy: Schema.Literal(TASK_PACKAGE.name),
+  name: Schema.String,
+  message: Schema.String,
+  location: Schema.optional(Schema.String),
+  filePath: Schema.optional(Schema.String),
+  taskName: Schema.optional(Schema.NullOr(Schema.String)),
+});
+
+export const reportError = (error: typeof TaskRaisedError.Type): PrintableError => {
+  const location = error.location ?? error.filePath ?? error.taskName ?? undefined;
+  return {
+    tag: error.name,
+    ...(location === undefined ? {} : { location }),
+    message: error.message === "" ? error.name : error.message,
+  };
+};
+
+const ErrnoCode = Schema.Struct({
+  code: Schema.String.check(Schema.isPattern(/^E[A-Z]+$/u)),
+});
+
+const SystemErrorMessage = Schema.Struct({ ...ErrnoCode.fields, message: Schema.String });
+
+const LocatedCauseMessage = Schema.Struct({ filePath: Schema.String, message: Schema.String });
+
+const FAILURE_VALUE_MAX_GRAPHEMES = 200;
+
+const FormattedFailureValue = Schema.Unknown.pipe(
+  Schema.decodeTo(
+    Schema.String,
+    SchemaTransformation.transform({
+      decode: (failureValue) =>
+        cutToGraphemes(Formatter.format(failureValue), FAILURE_VALUE_MAX_GRAPHEMES),
+      encode: (formatted) => formatted,
+    }),
+  ),
+);
+
+const CauseMessage = Schema.Union([
+  LocatedCauseMessage,
+  Schema.Struct({ message: Schema.String }),
+  Schema.String,
+  FormattedFailureValue,
+]);
+
+const isLocatedCauseMessage = Schema.is(LocatedCauseMessage);
+
+export const THROWN_VALUE_WITHOUT_MESSAGE = "a thrown value that has no message";
+
+const describeDecodedCause = (decoded: typeof CauseMessage.Type) => {
+  const message = Predicate.isString(decoded) ? decoded : decoded.message;
+  const description = message === "" ? THROWN_VALUE_WITHOUT_MESSAGE : message;
+  const hasLocation = !Predicate.isString(decoded) && isLocatedCauseMessage(decoded);
+  return hasLocation ? `${decoded.filePath} ${description}` : description;
+};
+
+const restatesItsCause = (reason: PlatformError.PlatformError["reason"]) =>
+  reason.description === String(reason.cause) ||
+  Option.exists(
+    Schema.decodeUnknownOption(Schema.Struct({ message: Schema.String }))(reason.cause),
+    (cause) => cause.message === reason.description,
+  );
+
+const describePlatformError = (platformError: PlatformError.PlatformError) =>
+  Option.getOrElse(
+    Option.map(
+      Option.filter(
+        Schema.decodeUnknownOption(SystemErrorMessage)(platformError.reason.cause),
+        () =>
+          platformError.reason.description === undefined || restatesItsCause(platformError.reason),
+      ),
+      (systemError) => systemError.message,
+    ),
+    () => platformError.reason.description ?? platformError.message,
+  );
+
+export const describeCauseMessage = (cause: unknown) =>
+  Option.match(Schema.decodeUnknownOption(Schema.instanceOf(PlatformError.PlatformError))(cause), {
+    onSome: describePlatformError,
+    onNone: () =>
+      Option.match(Schema.decodeUnknownOption(CauseMessage)(cause), {
+        onSome: describeDecodedCause,
+        onNone: () => "a failure value that cannot be formatted",
+      }),
+  });
+
+export const UNTAGGED_FAILURE_TAG = "UntaggedFailure";
+
+export class UntaggedFailure extends Schema.TaggedError<UntaggedFailure>()(UNTAGGED_FAILURE_TAG, {
+  ...TASK_ERROR_FIELDS,
+  failureMessage: Schema.String,
+  location: Schema.optional(Schema.String),
+}) {
+  public override get message() {
+    return this.failureMessage;
+  }
+}
+
+export class CauseWithoutFailure extends Schema.TaggedError<CauseWithoutFailure>()(
+  "CauseWithoutFailure",
+  { ...TASK_ERROR_FIELDS, details: Schema.String },
+) {
+  public override get message() {
+    return "was interrupted without a failure";
+  }
+}