cronfish 0.12.0

package/examples/one-time/cleanup.ts

@@ -0,0 +1,25 @@
+// One-shot TypeScript job. Like a recurring `.ts` it exports a top-level `config`
+// object and a default async function — but the config carries `run_at:` instead of
+// `schedule:`. Fires exactly once at `run_at`, then archives itself to
+// `~/Library/Application Support/cronfish/done/` (outside the repo).
+//
+// One-time jobs MUST be idempotent: launchd can re-fire on restart, unsleep, or load
+// spikes. Cronfish takes a flock and checks `executed_at` before invoking you, but the
+// window between "start" and "stamp" can still repeat — so make the work safe to redo.
+
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+export const config = {
+  run_at: "+1h", // relative to file mtime (s|m|h|d), OR an absolute ISO timestamp
+  enabled: false, // flip on with `cronfish enable one-time/cleanup-ts`
+  timeout: 120,
+};
+
+export default async function run(): Promise<void> {
+  // Deleting an already-deleted path is a no-op — naturally idempotent.
+  const stale = join(tmpdir(), "my-app-scratch");
+  await rm(stale, { recursive: true, force: true });
+  console.log(`cleaned ${stale}`);
+}

package/examples/one-time/reminder.md

@@ -0,0 +1,22 @@
+---
+run_at: "+10s" # relative to file mtime (s|m|h|d), OR an absolute ISO timestamp
+model: haiku
+enabled: false # flip on with `cronfish enable one-time/reminder-md`
+timeout: 60
+---
+
+One-shot reminder. Fires once at `run_at`, then archives itself to
+`~/Library/Application Support/cronfish/done/` — outside the repo.
+
+Swap the relative `+10s` for an absolute time when you mean a real reminder, e.g.:
+
+```
+run_at: 2026-07-01T15:00:00-04:00
+```
+
+Body (this is the Claude prompt that runs once):
+
+Post a Slack DM / write a note that says: "Reminder: stand up and stretch." Then stop.
+Do nothing else. This job must tolerate being invoked twice and do no harm on the second
+run — cronfish's flock + `executed_at` guard normally prevents that, but write idempotent
+bodies anyway.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "cronfish",
+  "version": "0.12.0",
+  "description": "A file-based job scheduler for macOS. Drop a script in a folder; launchd runs it on a schedule.",
+  "type": "module",
+  "bin": {
+    "cronfish": "./src/cli.ts"
+  },
+  "engines": {
+    "bun": ">=1.0"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build:ui": "cd ui && bun install && bun run build"
+  },
+  "files": [
+    "src",
+    "templates",
+    "examples",
+    "ui/dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cron",
+    "scheduler",
+    "launchd",
+    "macos",
+    "bun",
+    "automation",
+    "claude",
+    "task-scheduler"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/goldcaddy77/cronfish.git"
+  },
+  "homepage": "https://github.com/goldcaddy77/cronfish#readme",
+  "bugs": {
+    "url": "https://github.com/goldcaddy77/cronfish/issues"
+  },
+  "license": "MIT",
+  "author": "Dan Caddigan"
+}

package/src/alerts/dispatch.ts

@@ -0,0 +1,134 @@
+// Runner-side alert dispatch. Reads .cronfish.json alerts config, resolves
+// the adapter for a job, builds the payload, and fires safely.
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { InvocationStatus } from "../db.ts";
+import type { JobMeta, OnFailure } from "../jobs.ts";
+import { buildRegistry } from "./registry.ts";
+import { safeNotify, type AlertOutcome } from "./safe.ts";
+import type { AlertPayload, AlertStatus, AlertsConfig } from "./types.ts";
+
+export interface ConsumerAlertsConfig {
+  alerts?: AlertsConfig;
+  ui?: { public_url?: string };
+}
+
+export function loadConsumerAlertsConfig(
+  consumerRoot: string,
+): ConsumerAlertsConfig {
+  const path = join(consumerRoot, ".cronfish.json");
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as ConsumerAlertsConfig;
+  } catch {
+    return {};
+  }
+}
+
+export function chooseAdapterName(
+  onFailure: OnFailure | undefined,
+  cfg: AlertsConfig | undefined,
+): string | null {
+  const fromJob = onFailure?.notify?.trim();
+  if (fromJob) return fromJob === "none" ? null : fromJob;
+  const fromFleet = cfg?.on_failure?.notify?.trim();
+  if (fromFleet) return fromFleet === "none" ? null : fromFleet;
+  return null;
+}
+
+export function alertStatusFor(
+  invocationStatus: InvocationStatus,
+): AlertStatus | null {
+  if (invocationStatus === "fail") return "fail";
+  if (invocationStatus === "timeout") return "timeout";
+  if (invocationStatus === "crashed") return "crashed";
+  return null;
+}
+
+const LOG_TAIL_LINES = 20;
+const LOG_TAIL_MAX_BYTES = 4 * 1024;
+
+export function readLogTail(logPath: string): string {
+  try {
+    if (!existsSync(logPath)) return "";
+    const stat = statSync(logPath);
+    const start = Math.max(0, stat.size - 64 * 1024);
+    const fd = readFileSync(logPath);
+    const slice = fd.subarray(start).toString("utf-8");
+    const lines = slice.split(/\r?\n/);
+    if (lines.length === 0) return "";
+    // Drop the partial first line if we sliced mid-file.
+    const trimmed = start > 0 ? lines.slice(1) : lines;
+    const tail = trimmed.slice(-LOG_TAIL_LINES).join("\n");
+    if (Buffer.byteLength(tail, "utf-8") <= LOG_TAIL_MAX_BYTES) return tail;
+    // Truncate from the front (keep tail end) until under the cap.
+    let lo = 0;
+    let hi = tail.length;
+    while (lo < hi) {
+      const mid = Math.floor((lo + hi) / 2);
+      const candidate = tail.slice(mid);
+      if (Buffer.byteLength(candidate, "utf-8") <= LOG_TAIL_MAX_BYTES) hi = mid;
+      else lo = mid + 1;
+    }
+    return tail.slice(lo);
+  } catch {
+    return "";
+  }
+}
+
+export function buildUiUrl(
+  cfg: ConsumerAlertsConfig,
+  invocationId: number,
+): string | null {
+  const base = cfg.ui?.public_url?.trim();
+  if (!base) return null;
+  return `${base.replace(/\/$/, "")}/runs/${invocationId}`;
+}
+
+export interface DispatchInput {
+  job: JobMeta;
+  invocationId: number;
+  invocationStatus: InvocationStatus;
+  alertStatus: AlertStatus; // override for `recovered` / `test`
+  exitCode: number | null;
+  durationMs: number;
+  startedAt: string;
+  logPath: string;
+  consumerRoot: string;
+}
+
+export type DispatchOutcome =
+  | { kind: "skipped" }
+  | { kind: "sent" }
+  | { kind: "error"; error: string };
+
+export async function dispatchAlert(
+  input: DispatchInput,
+): Promise<DispatchOutcome> {
+  const cfg = loadConsumerAlertsConfig(input.consumerRoot);
+  const adapterName = chooseAdapterName(input.job.on_failure, cfg.alerts);
+  if (!adapterName) return { kind: "skipped" };
+  const registry = buildRegistry(cfg.alerts);
+  if (!registry.has(adapterName)) {
+    // Unknown adapter — treat as an error outcome (configuration bug).
+    const msg = `unknown adapter "${adapterName}"`;
+    console.error(`[cronfish] alert dispatch: ${msg}`);
+    return { kind: "error", error: msg };
+  }
+  const payload: AlertPayload = {
+    slug: input.job.slug,
+    status: input.alertStatus,
+    exit_code: input.exitCode,
+    duration_ms: input.durationMs,
+    started_at: input.startedAt,
+    log_tail: readLogTail(input.logPath),
+    ui_url: buildUiUrl(cfg, input.invocationId),
+  };
+  const outcome: AlertOutcome = await safeNotify(
+    registry.get(adapterName),
+    payload,
+  );
+  if (outcome.status === "sent") return { kind: "sent" };
+  return { kind: "error", error: outcome.error ?? "unknown error" };
+}

package/src/alerts/index.ts

@@ -0,0 +1,21 @@
+export { buildRegistry, type AdapterRegistry } from "./registry.ts";
+export { safeNotify, type AlertOutcome, type AlertOutcomeStatus } from "./safe.ts";
+export { createSlackAdapter, buildSlackBlocks } from "./slack.ts";
+export { createShellAdapter, payloadEnv } from "./shell.ts";
+export {
+  alertStatusFor,
+  buildUiUrl,
+  chooseAdapterName,
+  dispatchAlert,
+  loadConsumerAlertsConfig,
+  readLogTail,
+  type ConsumerAlertsConfig,
+  type DispatchInput,
+  type DispatchOutcome,
+} from "./dispatch.ts";
+export type {
+  Adapter,
+  AlertPayload,
+  AlertStatus,
+  AlertsConfig,
+} from "./types.ts";

package/src/alerts/registry.ts

@@ -0,0 +1,34 @@
+import { createShellAdapter } from "./shell.ts";
+import { createSlackAdapter } from "./slack.ts";
+import type { Adapter, AlertsConfig } from "./types.ts";
+
+export interface AdapterRegistry {
+  get(name: string): Adapter;
+  has(name: string): boolean;
+  defaultName(): string | null;
+}
+
+export function buildRegistry(cfg: AlertsConfig = {}): AdapterRegistry {
+  const map = new Map<string, Adapter>();
+  map.set("slack", createSlackAdapter(cfg.slack));
+  map.set("shell", createShellAdapter(cfg.shell));
+  return {
+    get(name) {
+      const a = map.get(name);
+      if (!a) {
+        const known = [...map.keys()].join(", ");
+        throw new Error(
+          `unknown alert adapter "${name}" (known: ${known}). ` +
+            `Check on_failure.notify / alerts.default in .cronfish.json.`,
+        );
+      }
+      return a;
+    },
+    has(name) {
+      return map.has(name);
+    },
+    defaultName() {
+      return cfg.default ?? null;
+    },
+  };
+}

package/src/alerts/safe.ts

@@ -0,0 +1,26 @@
+import type { Adapter, AlertPayload } from "./types.ts";
+
+export type AlertOutcomeStatus = "sent" | "error";
+
+export interface AlertOutcome {
+  status: AlertOutcomeStatus;
+  error: string | null;
+}
+
+// Failure-safe wrapper. Adapter throws → swallow, log to stderr, return error
+// outcome. Never re-raises. Caller persists outcome to cron_invocations.
+export async function safeNotify(
+  adapter: Adapter,
+  payload: AlertPayload,
+): Promise<AlertOutcome> {
+  try {
+    await adapter.notify(payload);
+    return { status: "sent", error: null };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(
+      `[cronfish] alert adapter "${adapter.name}" failed for ${payload.slug}: ${msg}`,
+    );
+    return { status: "error", error: msg };
+  }
+}

package/src/alerts/shell.ts

@@ -0,0 +1,63 @@
+import { spawn } from "node:child_process";
+import type { Adapter, AlertPayload, AlertsConfig } from "./types.ts";
+
+export function payloadEnv(payload: AlertPayload): Record<string, string> {
+  return {
+    CRONFISH_ALERT_SLUG: payload.slug,
+    CRONFISH_ALERT_STATUS: payload.status,
+    CRONFISH_ALERT_EXIT_CODE: payload.exit_code == null ? "" : String(payload.exit_code),
+    CRONFISH_ALERT_DURATION_MS: payload.duration_ms == null ? "" : String(payload.duration_ms),
+    CRONFISH_ALERT_STARTED_AT: payload.started_at,
+    CRONFISH_ALERT_UI_URL: payload.ui_url ?? "",
+    CRONFISH_ALERT_LOG_TAIL: payload.log_tail,
+  };
+}
+
+export interface ShellAdapterOptions {
+  // Inject a custom runner for tests. Receives the resolved command + env vars
+  // + JSON stdin and resolves on completion.
+  run?: (
+    command: string,
+    env: Record<string, string>,
+    stdin: string,
+  ) => Promise<void>;
+}
+
+function defaultRun(
+  command: string,
+  env: Record<string, string>,
+  stdin: string,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, {
+      shell: true,
+      env: { ...process.env, ...env },
+      stdio: ["pipe", "inherit", "inherit"],
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`shell adapter: command exited ${code}`));
+    });
+    child.stdin.end(stdin);
+  });
+}
+
+export function createShellAdapter(
+  cfg: AlertsConfig["shell"] = {},
+  opts: ShellAdapterOptions = {},
+): Adapter {
+  const command = cfg.command;
+  const run = opts.run ?? defaultRun;
+  return {
+    name: "shell",
+    async notify(payload: AlertPayload): Promise<void> {
+      if (!command) {
+        throw new Error("shell adapter: alerts.shell.command not configured");
+      }
+      const env = payloadEnv(payload);
+      const stdin = JSON.stringify(payload);
+      await run(command, env, stdin);
+    },
+  };
+}

package/src/alerts/slack.ts

@@ -0,0 +1,98 @@
+import type { Adapter, AlertPayload, AlertsConfig } from "./types.ts";
+
+const STATUS_EMOJI: Record<AlertPayload["status"], string> = {
+  fail: ":red_circle:",
+  timeout: ":hourglass:",
+  crashed: ":boom:",
+  missed: ":zzz:",
+  recovered: ":large_green_circle:",
+  test: ":test_tube:",
+};
+
+const STATUS_LABEL: Record<AlertPayload["status"], string> = {
+  fail: "FAIL",
+  timeout: "TIMEOUT",
+  crashed: "CRASHED",
+  missed: "MISSED",
+  recovered: "RECOVERED",
+  test: "TEST",
+};
+
+export function buildSlackBlocks(payload: AlertPayload): unknown[] {
+  const emoji = STATUS_EMOJI[payload.status] ?? ":grey_question:";
+  const label = STATUS_LABEL[payload.status] ?? payload.status.toUpperCase();
+  const ctxParts = [
+    `started ${payload.started_at}`,
+    payload.duration_ms != null ? `duration ${payload.duration_ms}ms` : null,
+    payload.exit_code != null ? `exit ${payload.exit_code}` : null,
+  ].filter((s): s is string => s != null);
+
+  const blocks: unknown[] = [
+    {
+      type: "header",
+      text: { type: "plain_text", text: `${emoji} ${label} — ${payload.slug}` },
+    },
+    {
+      type: "context",
+      elements: [{ type: "mrkdwn", text: ctxParts.join(" · ") }],
+    },
+  ];
+
+  if (payload.log_tail && payload.log_tail.trim().length > 0) {
+    blocks.push({
+      type: "section",
+      text: { type: "mrkdwn", text: "```\n" + payload.log_tail + "\n```" },
+    });
+  }
+
+  if (payload.ui_url) {
+    blocks.push({
+      type: "actions",
+      elements: [
+        {
+          type: "button",
+          text: { type: "plain_text", text: "View run" },
+          url: payload.ui_url,
+        },
+      ],
+    });
+  }
+
+  return blocks;
+}
+
+export interface SlackAdapterOptions {
+  webhookUrl?: string;
+  fetchFn?: typeof fetch;
+}
+
+export function createSlackAdapter(
+  cfg: AlertsConfig["slack"] = {},
+  opts: SlackAdapterOptions = {},
+): Adapter {
+  const envName = cfg.webhook_url_env ?? "CRONFISH_SLACK_WEBHOOK";
+  const fetchFn = opts.fetchFn ?? fetch;
+  return {
+    name: "slack",
+    async notify(payload: AlertPayload): Promise<void> {
+      const url = opts.webhookUrl ?? process.env[envName];
+      if (!url) {
+        throw new Error(
+          `slack adapter: env var ${envName} not set`,
+        );
+      }
+      const blocks = buildSlackBlocks(payload);
+      const res = await fetchFn(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ blocks }),
+      });
+      if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(
+          `slack adapter: webhook returned ${res.status} ${body.slice(0, 200)}`,
+        );
+      }
+    },
+  };
+}

package/src/alerts/types.ts

@@ -0,0 +1,34 @@
+// Alert payload + adapter interface. Pure types — no runtime imports.
+
+export type AlertStatus = "fail" | "timeout" | "crashed" | "missed" | "recovered" | "test";
+
+export interface AlertPayload {
+  slug: string;
+  status: AlertStatus;
+  exit_code: number | null;
+  duration_ms: number | null;
+  started_at: string; // ISO-8601
+  log_tail: string;   // last 20 lines, truncated to 4 KB
+  ui_url: string | null;
+}
+
+export interface Adapter {
+  readonly name: string;
+  notify(payload: AlertPayload): Promise<void>;
+}
+
+export interface AlertsConfig {
+  // Default adapter for `cronfish alerts test` (CLI) when no adapter arg is given.
+  default?: string;
+  // Fleet-wide on_failure default. Per-job frontmatter `on_failure` wins.
+  // Per-job `on_failure: { notify: "none" }` opts out of the fleet default.
+  on_failure?: {
+    notify?: string;
+  };
+  slack?: {
+    webhook_url_env?: string;
+  };
+  shell?: {
+    command?: string;
+  };
+}