@sshkeda/task 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephen Shkeda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# Task
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Delete your bash scripts! Your agent will thank you.
+
+Task is a task runner for Bun. It runs your builds, servers and CI, does independent work in parallel, waits only where one piece needs another, and stops everything at the end.
+
+## How it works
+
+A task is one named piece of work, such as a build, a typecheck or a server. When a task needs another task, it waits for that task and gets its result. Each task runs once per run, however many tasks need it. You write tasks in TypeScript, but the commands they start can use any runtime, such as Node or Python.
+
+Here's an example CI script. The end-to-end tests start your server, get its URL and test against it, while typecheck runs alongside:
+
+```ts
+// scripts/ci.ts
+import { Task } from "@sshkeda/task";
+import { Effect } from "effect";
+
+import { app } from "../src/app.ts";
+
+export const server = Task.make(
+  "server",
+  Effect.gen(function* () {
+    const server = Bun.serve({ port: 0, fetch: app.fetch });
+    return yield* Task.serve(server.url.href);
+  }),
+);
+export const typecheck = Task.make("typecheck", Task.exec("bunx", ["tsc", "--noEmit"]));
+export const e2e = Task.make(
+  "e2e",
+  Effect.gen(function* () {
+    const url = yield* server;
+    yield* Task.exec("bun", ["test", "e2e"], { env: { APP_URL: url } });
+  }),
+);
+export const ci = Task.make("ci", Task.allSettled([typecheck, e2e]));
+
+if (import.meta.main) {
+  Task.main(ci);
+}
+```
+
+Run it with `bun scripts/ci.ts`:
+
+```
+[ci] started
+[typecheck] started
+[e2e] started
+[server] started
+[server] serving after 0.0s
+[e2e] bun test v1.4.4
+[e2e]
+[e2e] e2e/health.test.ts:
+[e2e] (pass) the server is healthy [1.70ms]
+[e2e]
+[e2e]  1 pass
+[e2e]  0 fail
+[e2e]  1 expect() calls
+[e2e] Ran 1 test across 1 file. [9.00ms]
+[e2e] passed in 0.0s
+[typecheck] passed in 0.5s
+[ci] passed in 0.5s
+[server] closed
+passed: 4 tasks, 0.6s
+wrote the trace to /Users/you/.sshkeda-task/traces/my-app/2026-10-29T06-57-42.654Z-48677.jsonl
+```
+
+Every run writes an OpenTelemetry trace file, so you can see exactly what makes it slow.
+
+## What you get
+
+- **Multithreaded parallelism.** Task bodies run on a pool of worker threads, so independent tasks run side by side instead of blocking a single thread.
+- **Any runtime in one run.** Vitest on Node, `bun test` and a Python script can all run side by side.
+- **Values passed straight between tasks.** A task hands its result, such as a server's URL, to the tasks that use it, with no temporary files or wait scripts in between.
+- **Observable errors.** The last line names the command that failed and its error, so you don't have to dig through logs.
+- **Timeouts per task.** A hung test fails the run after the limit you set instead of blocking CI forever.
+- **Everything stops when the run ends.** Whether it passes, fails, times out or you press Ctrl-C, Task stops every task and the programs they started.
+
+## API
+
+- `Task.make(name, body, { timeout?, cleanup? })` makes a task from an Effect. `cleanup` is how long the task may take to stop, and it defaults to 5 seconds.
+- `Task.exec(command, args, { env?, cwd?, stdin?, secret? })` runs a command, returns its output and fails if it exits with an error. The command sees only `HOME`, `PATH` and `TMPDIR` from your environment, so pass anything else it needs in `env`. With `secret: true`, the output comes back as a `Redacted` value and stays out of logs.
+- `return yield* Task.serve(value)` ends a task's body but keeps the task running, such as a dev server, and hands `value` to the tasks that use it.
+- `Task.main(task)` runs a task and everything it uses, then exits.
+- `Task.all(tasks)` runs tasks in parallel and stops at the first failure. `Task.allSettled(tasks)` lets every task finish, then reports each failure.
+
+## Get started
+
+Task needs Bun 1.4.4 or newer.
+
+1. Install Task, Effect and Bun's types.
+
+   ```bash
+   bun add @sshkeda/task effect
+   bun add -d @types/bun
+   ```
+
+2. Add these options to `compilerOptions` in `tsconfig.json`.
+
+   ```json
+   "allowImportingTsExtensions": true,
+   "types": ["bun"]
+   ```
+
+3. Write your tasks in a TypeScript file, such as `scripts/ci.ts`.
+
+   ```ts
+   import { Task } from "@sshkeda/task";
+
+   export const test = Task.make("test", Task.exec("bun", ["test"]));
+
+   if (import.meta.main) {
+     Task.main(test);
+   }
+   ```
+
+4. Run the file.
+
+   ```bash
+   bun scripts/ci.ts
+   ```
+
+## Limits
+
+- Task runs only on Bun. Your commands can use any runtime, but your task files run on Bun.
+- Task bodies are Effect, so every step gets typed errors, retries and timeouts. If you haven't used Effect, your agent has.
+- Task has no caching. Every run runs every task it reaches.
+
+## Development
+
+To run the checks and tests, run `bun scripts/ci.ts`.
+
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@sshkeda/task",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "homepage": "https://github.com/sshkeda/task#readme",
+  "bugs": {
+    "url": "https://github.com/sshkeda/task/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sshkeda/task.git"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./errors": "./src/lib/errors/index.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@effect/platform-bun": "4.1.0",
+    "oxc-parser": "0.153.0"
+  },
+  "devDependencies": {
+    "@effect/tsgo": "0.55.0",
+    "@sshkeda/check": "^1.0.1",
+    "@sshkeda/task": "file:.",
+    "@types/bun": "1.4.3",
+    "effect": "4.1.0",
+    "typescript": "7.0.2"
+  },
+  "peerDependencies": {
+    "effect": "^4.1.0"
+  },
+  "engines": {
+    "bun": ">=1.4.4"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { Served, Serving, Tasks } from "./shared/task-services.ts";
+export * as Task from "./lib/task/index.ts";

package/src/lib/errors/index.ts

@@ -0,0 +1,15 @@
+export {
+  AwaitedTaskFailed,
+  CapturedCommandFailed,
+  CommandFailed,
+  CommandNotStarted,
+  CommandStandardInputFailed,
+  PrintableError,
+  ReportedErrors,
+  REPORTED_FAILURE_FIELDS,
+  SettledTasksFailed,
+  TaskError,
+  TaskNotMadeAtTopLevel,
+  TaskResultNotJson,
+  TaskWaitsOnItself,
+} from "./internal/errors.ts";

package/src/lib/errors/internal/errors.ts

@@ -0,0 +1,147 @@
+import { Effect, Schema } from "effect";
+
+import { TASK_ERROR_FIELDS, UNATTRIBUTED_FAILURE_FIELDS } from "../../../shared/error-fields.ts";
+import { findConstructingLocation } from "../../../shared/find-user-locations-in-stack-traces.ts";
+import { CauseWithoutFailure, describeCauseMessage } from "../../../shared/report-errors.ts";
+
+const isCauseWithoutFailure = Schema.is(CauseWithoutFailure);
+
+export class PrintableError extends Schema.Opaque<PrintableError>()(
+  Schema.Struct({
+    tag: Schema.String,
+    location: Schema.optional(Schema.String),
+    message: Schema.String,
+  }),
+) {}
+
+export class ReportedErrors extends Schema.TaggedError<ReportedErrors>()("ReportedErrors", {
+  ...TASK_ERROR_FIELDS,
+  reportedErrors: Schema.NonEmptyArray(PrintableError),
+}) {
+  public override get message() {
+    return this.reportedErrors.map((printableError) => printableError.message).join("\n");
+  }
+}
+
+export const REPORTED_FAILURE_FIELDS = {
+  taskName: Schema.String,
+  failures: Schema.NonEmptyArray(PrintableError),
+  details: Schema.optional(Schema.String),
+};
+
+export class TaskResultNotJson extends Schema.TaggedError<TaskResultNotJson>()(
+  "TaskResultNotJson",
+  {
+    ...TASK_ERROR_FIELDS,
+    taskName: Schema.String,
+    handedOver: Schema.Literals(["returned", "served"]),
+    valuePath: Schema.String,
+    valueDescription: Schema.String,
+  },
+) {
+  public override get message() {
+    return `${this.handedOver} ${this.valueDescription}${this.valuePath === "" ? "" : ` at ${this.valuePath}`}, which is not JSON`;
+  }
+}
+
+export class TaskError extends Schema.TaggedError<TaskError>()("TaskError", {
+  ...TASK_ERROR_FIELDS,
+  message: Schema.String,
+  location: Schema.UndefinedOr(Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.sync(findConstructingLocation)),
+  ),
+}) {}
+
+export class TaskNotMadeAtTopLevel extends Schema.TaggedError<TaskNotMadeAtTopLevel>()(
+  "TaskNotMadeAtTopLevel",
+  { ...TASK_ERROR_FIELDS, taskName: Schema.String, requestedTaskName: Schema.String },
+) {
+  public override get message() {
+    return `the module scan found no top-level Task.make("${this.requestedTaskName}") call`;
+  }
+}
+
+export class TaskWaitsOnItself extends Schema.TaggedError<TaskWaitsOnItself>()(
+  "TaskWaitsOnItself",
+  { ...TASK_ERROR_FIELDS, taskName: Schema.String, cycle: Schema.Array(Schema.String) },
+) {
+  public override get message() {
+    return `waits on itself through ${this.cycle.join(" -> ")}`;
+  }
+}
+
+export class AwaitedTaskFailed extends Schema.TaggedError<AwaitedTaskFailed>()(
+  "AwaitedTaskFailed",
+  { ...TASK_ERROR_FIELDS, ...UNATTRIBUTED_FAILURE_FIELDS, awaitedTaskName: Schema.String },
+) {
+  public override get message() {
+    return `${this.awaitedTaskName} failed`;
+  }
+}
+
+export class SettledTasksFailed extends Schema.TaggedError<SettledTasksFailed>()(
+  "SettledTasksFailed",
+  {
+    ...TASK_ERROR_FIELDS,
+    ...UNATTRIBUTED_FAILURE_FIELDS,
+    settledTaskCount: Schema.Int,
+    failedTaskNames: Schema.Array(Schema.String),
+  },
+) {
+  public override get message() {
+    return `${this.failedTaskNames.length} of ${this.settledTaskCount} ${this.settledTaskCount === 1 ? "task" : "tasks"} failed: ${this.failedTaskNames.join(", ")}`;
+  }
+}
+
+export class CommandFailed extends Schema.TaggedError<CommandFailed>()("CommandFailed", {
+  ...TASK_ERROR_FIELDS,
+  command: Schema.String,
+  code: Schema.Int,
+  standardOutput: Schema.String,
+  standardError: Schema.String,
+}) {
+  public override get message() {
+    return [
+      `${this.command} exited with code ${this.code}`,
+      this.standardOutput.trim(),
+      this.standardError.trim(),
+    ]
+      .filter((line) => line !== "")
+      .join("\n");
+  }
+}
+
+export class CapturedCommandFailed extends Schema.TaggedError<CapturedCommandFailed>()(
+  "CapturedCommandFailed",
+  {
+    ...TASK_ERROR_FIELDS,
+    command: Schema.String,
+    code: Schema.Int,
+    standardOutput: Schema.Redacted(Schema.String),
+    standardError: Schema.Redacted(Schema.String),
+  },
+) {
+  public override get message() {
+    return `${this.command} exited with code ${this.code}, and its captured output is not shown`;
+  }
+}
+
+export class CommandNotStarted extends Schema.TaggedError<CommandNotStarted>()(
+  "CommandNotStarted",
+  { ...TASK_ERROR_FIELDS, command: Schema.String, cause: Schema.Defect() },
+) {
+  public override get message() {
+    return `could not start ${this.command}: ${describeCauseMessage(this.cause)}`;
+  }
+}
+
+export class CommandStandardInputFailed extends Schema.TaggedError<CommandStandardInputFailed>()(
+  "CommandStandardInputFailed",
+  { ...TASK_ERROR_FIELDS, command: Schema.String, cause: Schema.Defect() },
+) {
+  public override get message() {
+    return isCauseWithoutFailure(this.cause)
+      ? `the standard input stream of ${this.command} ${this.cause.message}`
+      : `the standard input stream of ${this.command} failed with ${describeCauseMessage(this.cause)}`;
+  }
+}

package/src/lib/kill-leftover-processes/index.ts

@@ -0,0 +1,17 @@
+export {
+  forgetEndedProcessGroups,
+  killAllProcessGroups,
+  killTaskProcessGroups,
+} from "./internal/kill-process-groups.ts";
+export {
+  processGroupHasOnlyEndedMembers,
+  readProcessUnlessGone,
+} from "./internal/list-processes.ts";
+export { adoptSupervisorRunMarker, createRunMarker } from "./internal/mark-run-processes.ts";
+export { signalRunProcesses } from "./internal/signal-run-processes.ts";
+export {
+  findStartedGroupWitnessNow,
+  readLatestMemberStartTime,
+  recordLeaderExit,
+  startedProcessGroup,
+} from "./internal/started-process-groups.ts";

package/src/lib/kill-leftover-processes/internal/command-words.ts

@@ -0,0 +1,16 @@
+const BYTE_ORDER_MARK = "\uFEFF";
+
+export const commandWordsOf = (argumentWords: readonly string[]) =>
+  argumentWords
+    .map((argumentWord) =>
+      argumentWord.startsWith(BYTE_ORDER_MARK)
+        ? argumentWord.slice(BYTE_ORDER_MARK.length)
+        : argumentWord,
+    )
+    .filter((commandWord) => commandWord !== "");
+
+export const programNameOf = (argumentWords: readonly string[], commandName: string) => {
+  const [programPath] = commandWordsOf(argumentWords.slice(0, 1));
+  const programName = programPath?.slice(programPath.lastIndexOf("/") + 1) ?? "";
+  return programName === "" ? commandName : programName;
+};

package/src/lib/kill-leftover-processes/internal/find-process-ids.ts

@@ -0,0 +1,36 @@
+import type { Effect } from "effect";
+
+import type { listProcesses } from "./list-processes.ts";
+
+export const findDescendantProcessIds = (
+  listedProcesses: Effect.Success<ReturnType<typeof listProcesses>>,
+  processIdsAtThisDepth: readonly number[],
+  collectedProcessIds: readonly number[] = [],
+): readonly number[] => {
+  if (processIdsAtThisDepth.length === 0) {
+    return collectedProcessIds;
+  }
+  const collectedThroughThisDepth = [...collectedProcessIds, ...processIdsAtThisDepth];
+  return findDescendantProcessIds(
+    listedProcesses,
+    [...listedProcesses]
+      .filter(
+        ([processId, listedProcess]) =>
+          processIdsAtThisDepth.includes(listedProcess.parentProcessId) &&
+          !collectedThroughThisDepth.includes(processId),
+      )
+      .map(([processId]) => processId),
+    collectedThroughThisDepth,
+  );
+};
+
+export const findSessionProcessIds = (
+  listedProcesses: Effect.Success<ReturnType<typeof listProcesses>>,
+  sessionId: number | null,
+) =>
+  [...listedProcesses]
+    .filter(
+      ([processId, listedProcess]) =>
+        listedProcess.sessionId === sessionId && processId !== process.pid,
+    )
+    .map(([processId]) => processId);