@akshatmittal/invoker 0.1.0 → 0.3.0

package/README.md

@@ -10,7 +10,91 @@ validated JSON Output in Vitest metadata for reporters and later analysis.
 pnpm add -D @akshatmittal/invoker vitest
 ```
 
-Invoker supports Node 24 and Vitest 4.1.10 or newer within Vitest 4.
+Invoker supports Node 24.18.1 or newer within Node 24 and Vitest 4.1.10 or newer within Vitest 4.
+
+## Schedule GitHub Actions
+
+`@akshatmittal/invoker/github` runs code-defined GitHub Actions schedules from
+a small, long-running Node process. It is independent from the Vitest SDK, so a
+scheduler-only installation does not need Vitest.
+
+Create a GitHub App with repository **Actions: read and write**, disable its
+webhook, install it on the selected repositories, and generate a private key.
+No other repository, organization, user, OAuth, or webhook permissions are
+needed.
+
+Install the scheduler with t3-env and Zod in a plain ESM application:
+
+```sh
+npm install @akshatmittal/invoker @t3-oss/env-core zod
+```
+
+```js
+// schedule.mjs
+import { createEnv } from "@t3-oss/env-core";
+import { defineGitHubSchedule } from "@akshatmittal/invoker/github";
+import { z } from "zod";
+
+const env = createEnv({
+  server: {
+    GITHUB_APP_ID: z.coerce.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    GITHUB_APP_PRIVATE_KEY: z.string().min(1),
+  },
+  runtimeEnv: process.env,
+});
+
+await defineGitHubSchedule({
+  app: {
+    id: env.GITHUB_APP_ID,
+    privateKey: env.GITHUB_APP_PRIVATE_KEY,
+  },
+  schedules: [
+    {
+      cron: "0 9 * * 1",
+      timezone: "UTC",
+      repository: "acme/regressions",
+      workflow: "invoker.yml",
+      ref: "main",
+      inputs: { dataset: "weekly", publish: true },
+    },
+  ],
+});
+```
+
+Schedules use five-field cron expressions and default to UTC when `timezone`
+is omitted. Configuration is fixed at startup. Every repository installation
+and active workflow is validated before timers begin; GitHub validates the ref,
+`workflow_dispatch` declaration, and input schema when a Dispatch is due.
+
+Run exactly one replica. Dispatches may overlap, are not persisted or retried,
+and failures do not stop later occurrences. The process emits events through
+evlog's shared logger, so the host's filtering, sampling, redaction, and drain
+configuration applies. The module does not initialize or configure evlog.
+`SIGINT` and `SIGTERM` stop new Dispatches, await in-flight requests, and
+resolve the long-running promise.
+
+### Docker
+
+Keep `package.json`, `package-lock.json`, and `schedule.mjs` in a deployment
+directory and build this image:
+
+```dockerfile
+FROM node:24-slim
+
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+COPY schedule.mjs ./
+
+USER node
+CMD ["node", "schedule.mjs"]
+```
+
+Exclude `.env`, PEM, and private-key files from the build context. Inject
+`GITHUB_APP_ID` and the real multiline `GITHUB_APP_PRIVATE_KEY` through the
+runtime platform's secret mechanism; never bake them into the image. Use the
+platform's process-liveness check and restart policy with one replica. The
+scheduler intentionally has no HTTP health endpoint.
 
 ## Define a Workflow
 
@@ -20,10 +104,10 @@ import { defineTask } from "@akshatmittal/invoker";
 
 export const evaluateModels = defineTask({
   name: "evaluate-models",
-  matrix: {
+  matrix: async () => ({
     model: ["gpt-5", "gpt-5-mini"],
     dataset: ["support", "sales"],
-  },
+  }),
   setup: async ({ cases }) => loadFixtures(cases),
   run: async ({ matrix, setup, vitest }) => {
     vitest.expect(setup.has(matrix.dataset)).toBe(true);
@@ -41,9 +125,9 @@ export const evaluateModels = defineTask({
 ```
 
 ```ts
-// regressions/model/index.test.ts
+// regressions/workflows/model-regressions.test.ts
 import { defineWorkflow } from "@akshatmittal/invoker";
-import { evaluateModels } from "./tasks/evaluate-models.js";
+import { evaluateModels } from "../tasks/evaluate-models.js";
 
 defineWorkflow({
   name: "model-regressions",
@@ -55,16 +139,18 @@ defineWorkflow({
 });
 ```
 
-Matrix literals determine the exact `matrix` type, `setup` determines the exact
+The Matrix function runs during collection and its returned literal determines the exact
+`matrix` type. `setup` determines the exact
 shared setup type, and the exact JSON return type is retained on the Task.
+Axis names must be non-empty, enumerable strings that are not array indexes.
 Omitting `matrix` creates one Case with `{}`. Setup runs once per Task, Cases
 within that Task run concurrently, and teardown runs once after successful
 setup. Tasks run sequentially in their Workflow.
 
 ## Configure Vitest
 
-Invoker uses Vitest's built-in reporters. The JSON reporter includes each
-Case's data at `assertionResults[].meta.invoker`:
+The JSON reporter includes each Case's data at
+`assertionResults[].meta.invoker`:
 
 ```ts
 // vitest.config.ts
@@ -85,9 +171,13 @@ Run every Workflow or filter to one Task with ordinary Vitest commands:
 
 ```sh
 pnpm vitest run
-pnpm vitest run regressions/model/index.test.ts -t evaluate-models
+pnpm vitest run regressions/workflows/model-regressions.test.ts -t evaluate-models
 ```
 
+Define additional Workflows in separate `*.test.ts` files. Vitest discovers
+them automatically; Invoker does not scan directories or require a central
+index.
+
 The metadata envelope is stable and JSON-compatible:
 
 ```json
@@ -103,6 +193,48 @@ The metadata envelope is stable and JSON-compatible:
 report remains authoritative for status, failures, timing, hierarchy, and
 retries.
 
+## Notify Slack
+
+Invoker's optional Slack reporter posts one `Invoker Report` parent message per
+Vitest run. It places additional Workflow cards in the message thread so every
+Task table remains within Slack's row and character limits. Each card includes
+aggregate results, Workflow metadata, and a table of Task counts and durations.
+A shared footer contains the elapsed span from the first Case start to the final
+Case completion, a localized timestamp, and the optional run link. Final
+failures are posted in the same thread with one reply per failed Task in each
+Workflow. Unhandled run errors are reported once. Delivery failures are
+isolated to the affected reply. Ambiguous transport failures are not retried;
+an explicit Slack rate-limit rejection is reattempted only after its required
+delay.
+
+```ts
+import { slackReporter } from "@akshatmittal/invoker/slack";
+import { defineConfig } from "vitest/config";
+
+const runUrl =
+  process.env.GITHUB_ACTIONS === "true"
+    ? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
+    : undefined;
+
+export default defineConfig({
+  test: {
+    reporters: [
+      "tree",
+      slackReporter({
+        token: process.env.SLACK_BOT_TOKEN!,
+        channel: process.env.SLACK_CHANNEL_ID!,
+        runUrl,
+      }),
+    ],
+  },
+});
+```
+
+Create a Slack app with the `chat:write` bot scope, install it to the workspace,
+and expose its bot token and target channel ID as `SLACK_BOT_TOKEN` and
+`SLACK_CHANNEL_ID`. Invite the bot to private target channels. Slack delivery
+failures produce a warning but do not change Vitest's exit status.
+
 ## GitHub Actions artifacts
 
 Create the output directory before Vitest and upload the report even when the
@@ -122,7 +254,7 @@ queries or reports. Invoker does not upload, index, or persist results itself.
 
 ## v1 scope
 
-Invoker does not provide a CLI, directory discovery, custom runner, custom
-reporter, configuration helper, Task-level parallelism, matrix include/exclude,
-or hosted result storage. Use Vitest configuration and your CI runner for those
-concerns.
+Invoker does not provide a CLI, directory discovery, custom runner, general
+reporter framework, configuration helper, Task-level parallelism, matrix
+include/exclude, or hosted result storage. Use Vitest configuration and your CI
+runner for those concerns.

package/dist/github.d.mts

@@ -0,0 +1,22 @@
+//#region src/github/types.d.ts
+type WorkflowInput = string | number | boolean;
+type GitHubSchedule = {
+  readonly cron: string;
+  readonly timezone?: string;
+  readonly repository: string;
+  readonly workflow: string | number;
+  readonly ref: string;
+  readonly inputs?: Readonly<Record<string, WorkflowInput>>;
+};
+type GitHubScheduleDefinition = {
+  readonly app: {
+    readonly id: number;
+    readonly privateKey: string;
+  };
+  readonly schedules: readonly [GitHubSchedule, ...GitHubSchedule[]];
+};
+//#endregion
+//#region src/github.d.ts
+declare function defineGitHubSchedule(definition: GitHubScheduleDefinition): Promise<void>;
+//#endregion
+export { defineGitHubSchedule };

package/dist/github.mjs

@@ -0,0 +1,353 @@
+import { z } from "zod";
+import { Cron } from "croner";
+import { createAppAuth } from "@octokit/auth-app";
+import { request } from "@octokit/request";
+import { log } from "evlog";
+//#region src/github/client.ts
+const API_VERSION = "2026-03-10";
+const dispatchResponseSchema = z.object({
+	workflow_run_id: z.int().positive(),
+	html_url: z.url()
+});
+const requestFailureSchema = z.object({
+	status: z.int().optional(),
+	response: z.object({ headers: z.object({ "x-github-request-id": z.string().optional() }) }).optional()
+});
+const githubFailures = /* @__PURE__ */ new WeakMap();
+function createGitHubClient(app, signal) {
+	const apiRequest = request.defaults({
+		headers: {
+			accept: "application/vnd.github+json",
+			"x-github-api-version": API_VERSION
+		},
+		request: { signal }
+	});
+	const auth = createAppAuth({
+		appId: app.id,
+		privateKey: app.privateKey,
+		request: apiRequest,
+		log: { warn() {} }
+	});
+	const resolveInstallation = async (target) => {
+		try {
+			const authentication = await auth({ type: "app" });
+			return (await apiRequest("GET /repos/{owner}/{repo}/installation", {
+				owner: target.owner,
+				repo: target.repo,
+				headers: { authorization: `Bearer ${authentication.token}` }
+			})).data.id;
+		} catch (error) {
+			throw githubError(githubFailure(error, "resolve installation", target));
+		}
+	};
+	const installationToken = async (target, installationId) => {
+		try {
+			return (await auth({
+				type: "installation",
+				installationId,
+				repositoryNames: [target.repo],
+				permissions: { actions: "write" }
+			})).token;
+		} catch (error) {
+			throw githubError(githubFailure(error, "create installation token", target));
+		}
+	};
+	const resolveWorkflow = async (target, installationId) => {
+		try {
+			const token = await installationToken(target, installationId);
+			const response = await apiRequest("GET /repos/{owner}/{repo}/actions/workflows/{workflow_id}", {
+				owner: target.owner,
+				repo: target.repo,
+				workflow_id: target.workflow,
+				headers: { authorization: `Bearer ${token}` }
+			});
+			if (response.data.state !== "active") throw new Error("workflow is not active");
+			return response.data.id;
+		} catch (error) {
+			throw githubError(githubFailure(error, "resolve workflow", target));
+		}
+	};
+	const dispatch = async (target) => {
+		try {
+			const token = await installationToken(target, target.installationId);
+			const response = await apiRequest("POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches", {
+				owner: target.owner,
+				repo: target.repo,
+				workflow_id: target.workflowId,
+				ref: target.ref,
+				return_run_details: true,
+				inputs: target.inputs,
+				headers: { authorization: `Bearer ${token}` }
+			});
+			const data = dispatchResponseSchema.parse(response.data);
+			return {
+				runId: data.workflow_run_id,
+				webUrl: data.html_url
+			};
+		} catch (error) {
+			throw githubError(githubFailure(error, "dispatch workflow", target));
+		}
+	};
+	return {
+		dispatch,
+		resolveInstallation,
+		resolveWorkflow
+	};
+}
+function githubFailure(cause, operation, target) {
+	if (cause instanceof Error) {
+		const known = githubFailures.get(cause);
+		if (known) return known;
+	}
+	const parsed = requestFailureSchema.safeParse(cause);
+	const status = parsed.success ? parsed.data.status : void 0;
+	const requestId = parsed.success ? parsed.data.response?.headers["x-github-request-id"] : void 0;
+	return {
+		message: `GitHub ${operation}${target ? ` for ${target.repository} workflow ${String(target.workflow)}` : ""}: ${status === 404 ? "not found or inaccessible" : "request failed"}${status === void 0 ? "" : ` (${status})`}${requestId === void 0 ? "" : ` [request ${requestId}]`}`,
+		operation,
+		repository: target?.repository,
+		workflow: target?.workflow,
+		status,
+		requestId
+	};
+}
+function githubError(failure) {
+	const error = new Error(failure.message);
+	githubFailures.set(error, failure);
+	return error;
+}
+//#endregion
+//#region src/github/config.ts
+const GITHUB_SCHEDULE_OWNER = "GitHub Schedule";
+const inputSchema = z.union([
+	z.string(),
+	z.number().finite(),
+	z.boolean()
+]);
+const timezoneSchema = z.string().refine((timezone) => {
+	try {
+		new Intl.DateTimeFormat(void 0, { timeZone: timezone });
+		return true;
+	} catch {
+		return false;
+	}
+}, "expected a valid IANA timezone");
+const scheduleSchema = z.strictObject({
+	cron: z.string().min(1),
+	timezone: timezoneSchema.default("UTC"),
+	repository: z.string().regex(/^[^/\s]+\/[^/\s]+$/),
+	workflow: z.union([z.int().positive(), z.string().min(1).refine((value) => value.trim() === value && !value.includes("/"))]),
+	ref: z.string().refine((value) => value.trim() !== ""),
+	inputs: z.record(z.string(), inputSchema).refine((inputs) => Object.keys(inputs).length <= 25).refine((inputs) => JSON.stringify(inputs).length <= 65535).optional()
+});
+const definitionSchema = z.strictObject({
+	app: z.strictObject({
+		id: z.int().positive(),
+		privateKey: z.string().min(1)
+	}),
+	schedules: z.array(scheduleSchema).min(1)
+});
+function normalizeDefinition(value) {
+	const result = definitionSchema.safeParse(value);
+	if (!result.success) throw new TypeError(`${GITHUB_SCHEDULE_OWNER}: ${z.prettifyError(result.error)}`);
+	const schedules = result.data.schedules.map((schedule, index) => {
+		let validationJob;
+		try {
+			validationJob = new Cron(schedule.cron, {
+				mode: "5-part",
+				paused: true,
+				timezone: schedule.timezone
+			});
+			validationJob.nextRun();
+		} catch {
+			throw new TypeError(`${GITHUB_SCHEDULE_OWNER}.schedules[${index}].cron: expected a valid five-field cron expression`);
+		} finally {
+			validationJob?.stop();
+		}
+		const separator = schedule.repository.indexOf("/");
+		const owner = schedule.repository.slice(0, separator);
+		const repo = schedule.repository.slice(separator + 1);
+		return {
+			...schedule,
+			owner,
+			repo
+		};
+	});
+	return {
+		app: result.data.app,
+		schedules
+	};
+}
+function workflowKey(schedule) {
+	return `${schedule.repository}\0${String(schedule.workflow)}`;
+}
+//#endregion
+//#region src/github/events.ts
+const SERVICE = "github-schedule";
+function logStartup(schedules, repositories, workflows, failure) {
+	log[failure ? "error" : "info"]({
+		service: SERVICE,
+		event: "github_schedule.startup",
+		schedules,
+		repositories,
+		workflows,
+		...failure ? {
+			outcome: "failure",
+			failure
+		} : { outcome: "success" }
+	});
+}
+function logDispatch(schedule, scheduledAt, result, failure) {
+	log[failure ? "error" : "info"]({
+		service: SERVICE,
+		event: "github_schedule.dispatch",
+		repository: schedule.repository,
+		workflow: schedule.workflow,
+		ref: schedule.ref,
+		cron: schedule.cron,
+		timezone: schedule.timezone,
+		scheduledAt,
+		...failure ? {
+			outcome: "failure",
+			failure
+		} : {
+			outcome: "success",
+			runId: result.runId,
+			runUrl: result.webUrl
+		}
+	});
+}
+function logShutdown(signal, drainedDispatches) {
+	log.info({
+		service: SERVICE,
+		event: "github_schedule.shutdown",
+		signal,
+		drainedDispatches,
+		outcome: "success"
+	});
+}
+//#endregion
+//#region src/github/scheduler.ts
+let schedulerActive = false;
+async function runGitHubSchedule(definition) {
+	let normalized;
+	try {
+		normalized = normalizeDefinition(definition);
+	} catch (error) {
+		logStartup(0, 0, 0, localFailure(error));
+		throw error;
+	}
+	const repositoryCount = new Set(normalized.schedules.map(({ repository }) => repository)).size;
+	const workflowCount = new Set(normalized.schedules.map(workflowKey)).size;
+	if (schedulerActive) {
+		const error = /* @__PURE__ */ new TypeError(`${GITHUB_SCHEDULE_OWNER}: another scheduler is already active`);
+		logStartup(normalized.schedules.length, repositoryCount, workflowCount, localFailure(error));
+		throw error;
+	}
+	schedulerActive = true;
+	const startupAbort = new AbortController();
+	const jobs = [];
+	const inFlight = /* @__PURE__ */ new Set();
+	let state = "starting";
+	let stopSignal;
+	let drainedCount = 0;
+	let resolveStop;
+	const stopRequested = new Promise((resolve) => {
+		resolveStop = resolve;
+	});
+	const isStopping = () => state === "stopping";
+	const removeSignalHandlers = () => {
+		process.removeListener("SIGINT", onSigint);
+		process.removeListener("SIGTERM", onSigterm);
+	};
+	const requestStop = (signal) => {
+		if (isStopping()) return;
+		const duringStartup = state === "starting";
+		state = "stopping";
+		stopSignal = signal;
+		drainedCount = inFlight.size;
+		jobs.forEach((job) => job.stop());
+		removeSignalHandlers();
+		if (duringStartup) startupAbort.abort();
+		resolveStop();
+	};
+	function onSigint() {
+		requestStop("SIGINT");
+	}
+	function onSigterm() {
+		requestStop("SIGTERM");
+	}
+	process.on("SIGINT", onSigint);
+	process.on("SIGTERM", onSigterm);
+	try {
+		const github = createGitHubClient(normalized.app, startupAbort.signal);
+		const installations = /* @__PURE__ */ new Map();
+		for (const schedule of normalized.schedules) if (!installations.has(schedule.repository)) installations.set(schedule.repository, await github.resolveInstallation(schedule));
+		const workflows = /* @__PURE__ */ new Map();
+		for (const schedule of normalized.schedules) {
+			const key = workflowKey(schedule);
+			if (!workflows.has(key)) workflows.set(key, await github.resolveWorkflow(schedule, installations.get(schedule.repository)));
+		}
+		if (isStopping()) {
+			await finishShutdown(inFlight, stopSignal, drainedCount);
+			return;
+		}
+		const schedules = normalized.schedules.map((schedule) => ({
+			...schedule,
+			installationId: installations.get(schedule.repository),
+			workflowId: workflows.get(workflowKey(schedule))
+		}));
+		for (const schedule of schedules) {
+			const job = new Cron(schedule.cron, {
+				catch: true,
+				mode: "5-part",
+				timezone: schedule.timezone
+			}, (currentJob) => {
+				if (state !== "running") return;
+				const scheduledAt = (currentJob.currentRun() ?? /* @__PURE__ */ new Date()).toISOString();
+				const dispatch = github.dispatch(schedule).then((result) => logDispatch(schedule, scheduledAt, result), (cause) => {
+					const failure = githubFailure(cause, "dispatch workflow", schedule);
+					logDispatch(schedule, scheduledAt, void 0, failure);
+					throw new Error(failure.message);
+				});
+				inFlight.add(dispatch);
+				dispatch.then(() => inFlight.delete(dispatch), () => inFlight.delete(dispatch));
+				return dispatch;
+			});
+			jobs.push(job);
+		}
+		state = "running";
+		logStartup(normalized.schedules.length, repositoryCount, workflowCount);
+		await stopRequested;
+		await finishShutdown(inFlight, stopSignal, drainedCount);
+	} catch (error) {
+		if (isStopping()) {
+			await finishShutdown(inFlight, stopSignal, drainedCount);
+			return;
+		}
+		jobs.forEach((job) => job.stop());
+		removeSignalHandlers();
+		schedulerActive = false;
+		const failure = githubFailure(error, "start scheduler");
+		logStartup(normalized.schedules.length, repositoryCount, workflowCount, failure);
+		throw githubError(failure);
+	}
+}
+async function finishShutdown(inFlight, signal, drainedCount) {
+	await Promise.allSettled(inFlight);
+	schedulerActive = false;
+	logShutdown(signal, drainedCount);
+}
+function localFailure(cause) {
+	return {
+		message: cause instanceof Error ? cause.message : `${GITHUB_SCHEDULE_OWNER}: startup validation failed`,
+		operation: "validate configuration"
+	};
+}
+//#endregion
+//#region src/github.ts
+function defineGitHubSchedule(definition) {
+	return runGitHubSchedule(definition);
+}
+//#endregion
+export { defineGitHubSchedule };

package/dist/index.d.mts

@@ -34,25 +34,22 @@ type TeardownContext<M extends Matrix, Setup> = SetupContext<M> & {
 declare const taskDefinitionBrand: unique symbol;
 interface TaskDefinition<Name extends string = string, M extends Matrix = Matrix, Setup = unknown, Output extends JsonValue = JsonValue> {
   readonly name: Name;
-  readonly matrix: M;
-  readonly [taskDefinitionBrand]: {
-    readonly setup: Setup;
-    readonly output: Output;
-  };
+  readonly matrix: () => Promise<M>;
+  readonly [taskDefinitionBrand]: true;
   readonly setup?: (context: SetupContext<M>) => Awaitable<Setup>;
   readonly run: (context: TaskContext<CaseCoordinates<M>, Setup>) => Awaitable<Output>;
   readonly teardown?: (context: TeardownContext<M, Setup>) => Awaitable<void>;
 }
 type TaskWithSetup<Name extends string, M extends Matrix, Setup, Output extends JsonValue> = {
   readonly name: Name;
-  readonly matrix?: M;
+  readonly matrix?: () => Promise<M>;
   readonly setup: (context: SetupContext<M>) => Awaitable<Setup>;
   readonly run: (context: TaskContext<CaseCoordinates<M>, Setup>) => Awaitable<Output>;
   readonly teardown?: (context: TeardownContext<M, Setup>) => Awaitable<void>;
 };
 type TaskWithoutSetup<Name extends string, M extends Matrix, Output extends JsonValue> = {
   readonly name: Name;
-  readonly matrix?: M;
+  readonly matrix?: () => Promise<M>;
   readonly setup?: never;
   readonly run: (context: TaskContext<CaseCoordinates<M>, undefined>) => Awaitable<Output>;
   readonly teardown?: never;
@@ -61,11 +58,8 @@ declare function defineTask<const Name extends string, const M extends Matrix =
 declare function defineTask<const Name extends string, const M extends Matrix = Record<never, never>, const Output extends JsonValue = JsonValue>(definition: TaskWithoutSetup<Name, M, Output>): TaskDefinition<Name, M, undefined, Output>;
 type AnyTaskDefinition = {
   readonly name: string;
-  readonly matrix: Matrix;
-  readonly [taskDefinitionBrand]: {
-    readonly setup: unknown;
-    readonly output: JsonValue;
-  };
+  readonly matrix: () => Promise<Matrix>;
+  readonly [taskDefinitionBrand]: true;
 };
 //#endregion
 //#region src/workflow.d.ts