@hackwaly/task 0.1.0

package/.editorconfig

@@ -0,0 +1,12 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

package/README.md

@@ -0,0 +1,308 @@
+# @hackwaly/task
+
+A lightweight, TypeScript-native task runner inspired by Turborepo. Define your build pipeline with code, not configuration files.
+
+## Features
+
+- 🚀 **TypeScript-first**: Define tasks in TypeScript with full type safety
+- 📦 **Dependency management**: Automatic task dependency resolution and execution
+- 👀 **Watch mode**: File watching with intelligent task re-execution
+- ⚡ **Parallel execution**: Run independent tasks concurrently
+- 🎯 **Persistent tasks**: Support for long-running processes (servers, watchers)
+- 🔄 **Interruptible tasks**: Graceful handling of task interruption
+- 📁 **Input/Output tracking**: File-based change detection for efficient rebuilds
+
+## Installation
+
+```bash
+npm install @hackwaly/task
+# or
+pnpm add @hackwaly/task
+# or
+yarn add @hackwaly/task
+```
+
+## Quick Start
+
+1. Create a `taskfile.ts` in your project root:
+
+```typescript
+import { configInit } from "@hackwaly/task";
+
+const { defineTask } = configInit(import.meta);
+
+export const build = defineTask({
+  name: "build",
+  command: "tsc --build",
+  inputs: ["src/**/*.ts", "tsconfig.json"],
+  outputs: ["dist/**/*.js"],
+});
+
+export const test = defineTask({
+  name: "test",
+  command: "vitest run",
+  dependsOn: [build],
+});
+
+export const dev = defineTask({
+  name: "dev",
+  command: "tsc --watch",
+  persistent: true,
+});
+
+export default build;
+```
+
+2. Run tasks:
+
+```bash
+# Run a single task
+npx task run build
+
+# Run multiple tasks
+npx task run build test
+
+# Run with watch mode
+npx task run build --watch
+
+# List available tasks
+npx task list
+```
+
+## Task Configuration
+
+Tasks are defined using the `defineTask` function with the following options:
+
+```typescript
+interface TaskConfig {
+  name: string;              // Task name (required)
+  description?: string;      // Task description for help text
+  command?: string | string[] | { program: string; args?: string[] };
+  env?: Record<string, string>;  // Environment variables
+  cwd?: string;              // Working directory (defaults to taskfile location)
+  inputs?: string[];         // Input file patterns (for change detection)
+  outputs?: string[];        // Output file patterns
+  persistent?: boolean;      // Whether task runs continuously (like servers)
+  interruptible?: boolean;   // Whether task can be interrupted safely
+  dependsOn?: TaskDef[];     // Task dependencies
+}
+```
+
+### Command Formats
+
+Commands can be specified in multiple formats:
+
+```typescript
+// String (parsed with shell-like parsing)
+command: "tsc --build --verbose"
+
+// Array
+command: ["tsc", "--build", "--verbose"]
+
+// Object
+command: {
+  program: "tsc",
+  args: ["--build", "--verbose"]
+}
+```
+
+### Dependencies
+
+Tasks can depend on other tasks. Dependencies are resolved automatically:
+
+```typescript
+export const generateTypes = defineTask({
+  name: "generate-types",
+  command: "generate-types src/schema.json",
+  outputs: ["src/types.ts"],
+});
+
+export const build = defineTask({
+  name: "build",
+  command: "tsc --build",
+  inputs: ["src/**/*.ts"],
+  dependsOn: [generateTypes],  // Runs generateTypes first
+});
+```
+
+### Persistent Tasks
+
+For long-running processes like development servers:
+
+```typescript
+export const server = defineTask({
+  name: "server",
+  command: "node server.js",
+  persistent: true,        // Runs continuously
+  interruptible: true,     // Can be stopped gracefully
+});
+```
+
+## Watch Mode
+
+Watch mode automatically re-runs tasks when their input files change:
+
+```bash
+npx task run build --watch
+```
+
+Features:
+- Monitors all input patterns defined in tasks
+- Ignores `node_modules` by default
+- Propagates changes through the dependency graph
+- Only reruns tasks that are affected by changes
+
+## Commands
+
+### `run <tasks...>`
+
+Run one or more tasks:
+
+```bash
+# Single task
+npx task run build
+
+# Multiple tasks
+npx task run lint test build
+
+# With watch mode
+npx task run build --watch
+```
+
+### `list` / `ls`
+
+List all available tasks:
+
+```bash
+npx task list
+```
+
+Shows task names and descriptions in a formatted table.
+
+## Examples
+
+### Basic Build Pipeline
+
+```typescript
+import { configInit } from "@hackwaly/task";
+
+const { defineTask } = configInit(import.meta);
+
+export const lint = defineTask({
+  name: "lint",
+  description: "Lint TypeScript files",
+  command: "eslint src/**/*.ts",
+  inputs: ["src/**/*.ts", ".eslintrc.json"],
+});
+
+export const typecheck = defineTask({
+  name: "typecheck",
+  description: "Type check TypeScript files",
+  command: "tsc --noEmit",
+  inputs: ["src/**/*.ts", "tsconfig.json"],
+});
+
+export const build = defineTask({
+  name: "build",
+  description: "Build the project",
+  command: "tsc --build",
+  inputs: ["src/**/*.ts", "tsconfig.json"],
+  outputs: ["dist/**/*.js"],
+  dependsOn: [lint, typecheck],
+});
+
+export const test = defineTask({
+  name: "test",
+  description: "Run tests",
+  command: "vitest run",
+  dependsOn: [build],
+});
+```
+
+### Development Workflow
+
+```typescript
+export const generateSchema = defineTask({
+  name: "generate-schema",
+  command: "generate-schema api.yaml",
+  inputs: ["api.yaml"],
+  outputs: ["src/generated/schema.ts"],
+});
+
+export const dev = defineTask({
+  name: "dev",
+  description: "Start development server",
+  command: "vite dev",
+  persistent: true,
+  interruptible: true,
+  dependsOn: [generateSchema],
+});
+
+export const buildWatch = defineTask({
+  name: "build:watch",
+  description: "Build in watch mode",
+  command: "tsc --watch",
+  persistent: true,
+  dependsOn: [generateSchema],
+});
+```
+
+## Advanced Usage
+
+### Monorepo Support
+
+Each package can have its own `taskfile.ts`:
+
+```typescript
+// packages/ui/taskfile.ts
+import { configInit } from "@hackwaly/task";
+
+const { defineTask } = configInit(import.meta);
+
+export const build = defineTask({
+  name: "build:ui",
+  command: "rollup -c",
+  inputs: ["src/**/*", "rollup.config.js"],
+  outputs: ["dist/**/*"],
+});
+
+// packages/app/taskfile.ts
+import { build as buildUI } from "../ui/taskfile.ts";
+
+export const build = defineTask({
+  name: "build:app",
+  command: "vite build",
+  dependsOn: [buildUI],  // Cross-package dependency
+});
+```
+
+### Custom Task Logic
+
+For complex tasks, you can provide custom logic:
+
+```typescript
+export const customTask = defineTask({
+  name: "custom",
+  async run(ctx) {
+    // Custom async logic
+    console.log("Running custom task...");
+
+    // Check if aborted
+    if (ctx.abort.aborted) {
+      return;
+    }
+
+    // Your custom logic here
+  },
+  inputs: ["src/**/*"],
+});
+```
+
+## Requirements
+
+- Node.js 18+ with `--experimental-strip-types` support
+- TypeScript 5.0+
+
+## License
+
+MIT

package/bin/task

@@ -0,0 +1,4 @@
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning --experimental-strip-types
+import { cliMain } from "../src/index.ts";
+
+await cliMain();

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@hackwaly/task",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": "github:hackwaly/task",
+  "bin": {
+    "task": "bin/task"
+  },
+  "main": "./src/index.ts",
+  "pnpm": {},
+  "dependencies": {
+    "ansi-styles": "^6.2.3",
+    "chokidar": "^4.0.3",
+    "commander": "^14.0.1",
+    "execa": "^9.6.0",
+    "micromatch": "^4.0.8",
+    "rxjs": "^7.8.2",
+    "string-argv": "^0.3.2"
+  },
+  "devDependencies": {
+    "@types/micromatch": "^4.0.9",
+    "@types/node": "^24.8.1"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,150 @@
+import { Command } from "commander";
+import process from "node:process";
+import type { TaskDef } from "./types.ts";
+import { start } from "./scheduler.ts";
+import { ReplaySubject } from "rxjs";
+import chokidar from "chokidar";
+import micromatch from "micromatch";
+import NodePath from "node:path";
+
+export async function cliMain(): Promise<void> {
+  const program = new Command()
+    .name("task")
+    .version("0.1.0")
+    .description("Just another task runner");
+  const runCommand = new Command()
+    .name("run")
+    .option("-w, --watch", "Watch mode")
+    .argument("<tasks...>", "Task(s) to run")
+    .action(async (taskNames: string[], options: { watch: boolean }) => {
+      const path = process.cwd();
+      const allTaskDefs = await import(NodePath.join(path, "taskfile.ts"));
+      const topTaskSet = new Set<TaskDef>();
+      for (const name of taskNames) {
+        const taskDef = allTaskDefs[name];
+        if (!taskDef) {
+          throw new Error(`Task "${name}" not found.`);
+        }
+        topTaskSet.add(taskDef);
+      }
+      const aborter = new AbortController();
+      const taskChan = new ReplaySubject<Set<TaskDef>>();
+      const loop = start(taskChan, {
+        abort: aborter.signal,
+      });
+      if (options.watch) {
+        const watchTargets = new Set<string>();
+        const watchSet = new Set<TaskDef>();
+        const addWatchDir = (task: TaskDef) => {
+          for (const dep of task.deps) {
+            addWatchDir(dep);
+          }
+          if (!task.meta.persistent || task.meta.interruptible) {
+            watchSet.add(task);
+            watchTargets.add(task.meta.cwd);
+          }
+        };
+        for (const task of topTaskSet) {
+          addWatchDir(task);
+        }
+        const watcher = chokidar.watch([...watchTargets], {
+          ignoreInitial: true,
+          ignored: (path) => /\bnode_modules\b/.test(path),
+        });
+        const dirtySeedSet = new Set<TaskDef>();
+        const flush = () => {
+          const dirtySet = new Set<TaskDef>();
+          const process = (task: TaskDef, buffer: TaskDef[]) => {
+            if (topTaskSet.has(task)) {
+              for (const t of buffer) {
+                dirtySet.add(t);
+              }
+              buffer.length = 0;
+            }
+            for (const invDep of task.invDeps) {
+              process(
+                invDep,
+                !invDep.meta.persistent || invDep.meta.interruptible
+                  ? [...buffer, invDep]
+                  : buffer
+              );
+            }
+          };
+          for (const task of dirtySeedSet) {
+            process(task, [task]);
+          }
+          dirtySeedSet.clear();
+          if (dirtySet.size > 0) {
+            taskChan.next(dirtySet);
+          }
+        };
+        watcher.on("all", (event, path) => {
+          for (const task of watchSet) {
+            const relPath = NodePath.relative(task.meta.cwd, path);
+            if (micromatch.isMatch(relPath, task.meta.inputs)) {
+              dirtySeedSet.add(task);
+            }
+          }
+          if (dirtySeedSet.size > 0) {
+            flush();
+          }
+        });
+        process.on("SIGINT", () => {
+          aborter.abort();
+          watcher.close();
+        });
+        taskChan.next(topTaskSet);
+      } else {
+        taskChan.next(topTaskSet);
+        taskChan.complete();
+      }
+      await loop;
+    });
+  const listCommand = new Command()
+    .name("list")
+    .alias("ls")
+    .description("List all available tasks")
+    .action(async () => {
+      const path = process.cwd();
+      const allTaskDefs = await import(NodePath.join(path, "taskfile.ts"));
+
+      // Get all exported tasks
+      const tasks: Array<{ name: string; description?: string }> = [];
+      for (const [exportName, taskDef] of Object.entries(allTaskDefs)) {
+        if (
+          exportName !== "default" &&
+          taskDef &&
+          typeof taskDef === "object" &&
+          "meta" in taskDef
+        ) {
+          const task = taskDef as TaskDef;
+          tasks.push({
+            name: task.meta.name,
+            description: task.meta.description,
+          });
+        }
+      }
+
+      if (tasks.length === 0) {
+        process.stdout.write("No tasks found in taskfile.ts\n");
+        return;
+      }
+
+      // Sort tasks by name
+      tasks.sort((a, b) => a.name.localeCompare(b.name));
+
+      // Find the longest task name for formatting
+      const maxNameLength = Math.max(...tasks.map((t) => t.name.length));
+
+      process.stdout.write("Available tasks:\n");
+      for (const task of tasks) {
+        const paddedName = task.name.padEnd(maxNameLength);
+        const description = task.description || "No description";
+        process.stdout.write(`  ${paddedName}  ${description}\n`);
+      }
+    });
+
+  program.addCommand(runCommand);
+  program.addCommand(listCommand);
+  await program.parseAsync();
+}

package/src/config.ts

@@ -0,0 +1,82 @@
+import type { Command, TaskDef, TaskMeta, TaskRunContext } from "./types.ts";
+import NodePath from "node:path";
+import { fileURLToPath } from "node:url";
+import { runCommand } from "./run.ts";
+import { parseArgsStringToArgv } from "string-argv";
+
+export interface TaskConfig {
+  name: string;
+  description?: string;
+  run?: (ctx: TaskRunContext) => Promise<void>;
+  command?: string | string[] | { program: string; args?: string[] };
+  env?: Record<string, string>;
+  cwd?: string;
+  inputs?: string[];
+  outputs?: string[];
+  persistent?: boolean;
+  // interactive?: boolean;
+  interruptible?: boolean;
+  // cache?: boolean;
+  dependsOn?: [TaskDef];
+}
+
+export interface ConfigAPI {
+  defineTask(config: TaskConfig): TaskDef;
+}
+
+function normalizeCommand(
+  command: string | string[] | { program: string; args?: string[] } | undefined
+): Command | undefined {
+  if (typeof command === "string") {
+    const argv = parseArgsStringToArgv(command);
+    return { program: argv[0]!, args: argv.slice(1) };
+  }
+  if (Array.isArray(command)) {
+    return { program: command[0]!, args: command.slice(1) };
+  }
+  if (command !== undefined) {
+    return { program: command.program, args: command.args ?? [] };
+  }
+  return undefined;
+}
+
+export function configInit(importMeta: ImportMeta): ConfigAPI {
+  return {
+    defineTask: (config: TaskConfig): TaskDef => {
+      const command = normalizeCommand(config.command);
+      const meta: TaskMeta = {
+        name: config.name,
+        description: config.description,
+        cwd: config.cwd ?? NodePath.dirname(fileURLToPath(importMeta.url)),
+        env: config.env ?? {},
+        inputs: config.inputs ?? ["**/*"],
+        outputs: config.outputs ?? ["**/*"],
+        persistent: config.persistent ?? false,
+        // interactive: config.interactive ?? false,
+        interruptible: config.interruptible ?? false,
+      };
+      const def: TaskDef = {
+        run:
+          config.run ??
+          (async (ctx: TaskRunContext) => {
+            if (command !== undefined) {
+              await runCommand(command, meta, ctx);
+            }
+          }),
+        meta: meta,
+        deps: new Set(),
+        invDeps: new Set(),
+      };
+      for (const dep of config.dependsOn ?? []) {
+        def.deps.add(dep);
+        if (dep.meta.persistent && !def.meta.persistent) {
+          throw new Error(
+            `Task "${def.meta.name}" depends on persistent task "${dep.meta.name}", so it must also be marked as persistent.`
+          );
+        }
+        dep.invDeps.add(def);
+      }
+      return def;
+    },
+  };
+}

package/src/errors.ts

@@ -0,0 +1,5 @@
+export class InvariantViolation extends Error {
+  get name(): string {
+    return InvariantViolation.name;
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { cliMain } from "./cli.ts";
+export { configInit } from "./config.ts";

package/src/run.ts

@@ -0,0 +1,31 @@
+import type { Command, TaskMeta, TaskRunContext } from "./types.ts";
+import { execa } from "execa";
+import process from "node:process";
+import styles from "ansi-styles";
+
+export async function runCommand(
+  command: Command,
+  meta: TaskMeta,
+  ctx: TaskRunContext
+): Promise<void> {
+  const { abort } = ctx;
+  const { name, cwd, env } = meta;
+
+  const transform = function* (line: string) {
+    const lastCR = line.lastIndexOf("\r");
+    const line2 = lastCR >= 0 ? line.substring(lastCR + 1, line.length) : line;
+    const line3 = line2.replace(/\x1bc|\x1b\[2J(?:\x1b\[H)?/g, "");
+    yield `${name} | ${line3}`;
+  };
+
+  process.stdout.write(`▪▪▪▪ ${styles.bold.open}${name}${styles.bold.close}\n`);
+  await execa({
+    // @ts-expect-error
+    cwd: cwd,
+    env: env,
+    stdout: [transform, "inherit"],
+    stderr: [transform, "inherit"],
+    cancelSignal: abort,
+    reject: false,
+  })`${command.program} ${command.args}`;
+}

package/src/scheduler.ts

@@ -0,0 +1,156 @@
+import type { TaskDef } from "./types.ts";
+import { InvariantViolation } from "./errors.ts";
+import { firstValueFrom, Subject, type Observable } from "rxjs";
+
+export async function start(
+  taskChan: Observable<Set<TaskDef>>,
+  options: {
+    abort: AbortSignal;
+  }
+): Promise<void> {
+  const abort = options.abort;
+
+  // A pending task is dirty, but a dirty task may not be pending
+  const dirtySet = new Set<TaskDef>();
+  const pendingSet = new Set<TaskDef>();
+  const upToDateSet = new Set<TaskDef>();
+
+  const readySignal = new Subject<void>();
+  const readySet = new Set<TaskDef>();
+  const runningSet = new Map<
+    TaskDef,
+    {
+      promise: Promise<void>;
+      aborter: AbortController;
+    }
+  >();
+  const abortedRunningSet = new Map<TaskDef, Promise<void>>();
+
+  const isReady = (task: TaskDef) => {
+    if (!dirtySet.has(task)) throw new InvariantViolation();
+
+    if (pendingSet.has(task)) {
+      return false;
+    }
+
+    for (const dep of task.deps) {
+      if (!upToDateSet.has(dep)) {
+        return false;
+      }
+    }
+    return true;
+  };
+
+  const checkReady = (task: TaskDef) => {
+    if (isReady(task)) {
+      dirtySet.delete(task);
+      readySet.add(task);
+      readySignal.next();
+
+      // Mark inverse dependencies as pending, so they won't become ready
+      for (const invDep of task.invDeps) {
+        if (dirtySet.has(invDep)) {
+          pendingSet.add(invDep);
+        }
+      }
+    }
+  };
+
+  const cancel = (task: TaskDef) => {
+    if (!runningSet.has(task)) throw new InvariantViolation();
+
+    const { promise, aborter } = runningSet.get(task)!;
+    runningSet.delete(task);
+    abortedRunningSet.set(task, promise);
+    aborter.abort();
+  };
+
+  const addDirtyAndCheckReady = (task: TaskDef) => {
+    if (runningSet.has(task)) {
+      cancel(task);
+      runningSet.delete(task);
+    } else if (readySet.has(task)) {
+      readySet.delete(task);
+    }
+
+    dirtySet.add(task);
+
+    if (upToDateSet.has(task)) {
+      upToDateSet.delete(task);
+    } else {
+      for (const dep of task.deps) {
+        addDirtyAndCheckReady(dep);
+      }
+    }
+
+    checkReady(task);
+  };
+
+  const runTask = async (task: TaskDef, abort: AbortSignal) => {
+    if (runningSet.has(task)) {
+      const { promise, aborter } = runningSet.get(task)!;
+      aborter.abort();
+      await Promise.allSettled([promise]);
+    }
+
+    await task.run({ abort });
+    upToDateSet.add(task);
+    for (const invDep of task.invDeps) {
+      if (pendingSet.has(invDep)) {
+        pendingSet.delete(invDep);
+        checkReady(invDep);
+      }
+    }
+  };
+
+  let noMoreTasks = false;
+  taskChan.subscribe({
+    next: (tasks) => {
+      for (const task of tasks) {
+        addDirtyAndCheckReady(task);
+      }
+    },
+    complete: () => {
+      noMoreTasks = true;
+    },
+  });
+
+  const runLoop = async () => {
+    while (!abort.aborted) {
+      if (readySet.size === 0) {
+        await firstValueFrom(readySignal);
+        continue;
+      }
+      // TODO: limit the concurrency
+      for (const task of readySet) {
+        const aborter = new AbortController();
+        const promise = runTask(task, aborter.signal).finally(() => {
+          // Clean up abortedRunningSet if this was the last run
+          const wait = abortedRunningSet.get(task);
+          if (wait === promise) {
+            abortedRunningSet.delete(task);
+          }
+          const runningEntry = runningSet.get(task);
+          if (runningEntry !== undefined && runningEntry.promise === promise) {
+            runningSet.delete(task);
+          }
+        });
+        runningSet.set(task, { promise, aborter });
+      }
+      readySet.clear();
+      if (dirtySet.size === 0 && noMoreTasks) {
+        break;
+      }
+    }
+  };
+
+  abort.addEventListener("abort", () => {
+    for (const task of runningSet.keys()) {
+      cancel(task);
+    }
+    runningSet.clear();
+  });
+
+  await runLoop();
+  await Promise.allSettled(abortedRunningSet.values());
+}

package/src/types.ts

@@ -0,0 +1,27 @@
+export interface Command {
+  program: string;
+  args: string[];
+}
+
+export interface TaskRunContext {
+  abort: AbortSignal;
+}
+
+export interface TaskMeta {
+  name: string;
+  description: string | undefined;
+  cwd: string;
+  env: Record<string, string>;
+  inputs: string[];
+  outputs: string[];
+  persistent: boolean;
+  // interactive: boolean;
+  interruptible: boolean;
+}
+
+export interface TaskDef {
+  run: (ctx: TaskRunContext) => Promise<void>;
+  meta: TaskMeta;
+  deps: Set<TaskDef>;
+  invDeps: Set<TaskDef>;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "es2024",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "isolatedModules": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true
+  }
+}