@pragma-sh/automations 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# @pragma-sh/automations
+
+Write a Pragma automation. Part of [Pragma](https://github.com/pragma-sh/pragma) — a desktop workspace for
+running persistent, worktree-scoped coding agents.
+
+Authoring API for trusted TypeScript tasks a Pragma host runs on a cron
+schedule, on a workspace event, or on demand.
+
+```sh
+bun add @pragma-sh/automations
+```
+
+```ts
+import { defineAutomation } from "@pragma-sh/automations";
+
+export default defineAutomation({
+  name: "Nightly cleanup",
+  trigger: { kind: "cron", expression: "0 3 * * *" },
+  async run({ client }) {
+    /* … */
+  },
+});
+```
+
+Docs: <https://pragma-app.sh/docs/automations>
+
+## License
+
+AGPL-3.0-only. See [LICENSE](https://github.com/pragma-sh/pragma/blob/main/LICENSE).

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@pragma-sh/automations",
+  "version": "0.1.0",
+  "description": "Pragma automation authoring API and host sidecar runtime.",
+  "homepage": "https://github.com/pragma-sh/pragma#readme",
+  "bugs": "https://github.com/pragma-sh/pragma/issues",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pragma-sh/pragma.git",
+    "directory": "packages/automations"
+  },
+  "bin": {
+    "pragma-automations": "src/cli.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun --bun vitest run",
+    "lint": "oxlint .",
+    "build:sidecar": "bun build src/cli.ts --compile --minify --outfile dist/pragma-automations"
+  },
+  "dependencies": {
+    "@pragma-sh/sidecar-kit": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,315 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { builtinModules } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { readStdinLines } from "@pragma-sh/sidecar-kit";
+
+import { findFiles } from "./find.ts";
+import { defineAutomation, type AutomationContext, type AutomationDefinition } from "./index.ts";
+
+declare const Bun: {
+  spawn(
+    command: string[],
+    options: { cwd: string; stdout: "pipe"; stderr: "pipe" },
+  ): {
+    exited: Promise<number>;
+    stderr: ReadableStream<Uint8Array>;
+  };
+};
+
+type Scope = "global" | "local";
+
+interface LoadCommand {
+  type: "load";
+  id: string;
+  path: string;
+  sourceVersion?: string;
+  root: string;
+  scope: Scope;
+  projectId?: string | null;
+  worktreeId?: string | null;
+}
+
+interface UnloadCommand {
+  type: "unload" | "runNow" | "reload";
+  id: string;
+}
+
+type Command = LoadCommand | UnloadCommand;
+
+interface LoadedAutomation {
+  command: LoadCommand;
+  definition: AutomationDefinition;
+  dispose?: () => void;
+}
+
+const loaded = new Map<string, LoadedAutomation>();
+const builtins = new Set([...builtinModules, ...builtinModules.map((name) => `node:${name}`)]);
+
+function emit(event: Record<string, unknown>): void {
+  process.stdout.write(`${JSON.stringify(event)}\n`);
+}
+
+function emitError(id: string | undefined, error: unknown): void {
+  const message = error instanceof Error ? error.message : String(error);
+  emit({ type: "error", id, error: message });
+}
+
+function cacheDir(): string {
+  if (process.env.PRAGMA_AUTOMATIONS_CACHE) return process.env.PRAGMA_AUTOMATIONS_CACHE;
+  const home = process.env.HOME ?? process.cwd();
+  return join(home, ".pragma", "automation-cache");
+}
+
+function packageName(specifier: string): string {
+  if (specifier.startsWith("@")) return specifier.split("/").slice(0, 2).join("/");
+  return specifier.split("/")[0] ?? specifier;
+}
+
+const IMPORT_PATTERNS = [
+  /import\s+(?:[^"']+\s+from\s+)?["']([^"']+)["']/g,
+  /export\s+[^"']+\s+from\s+["']([^"']+)["']/g,
+  /import\(\s*["']([^"']+)["']\s*\)/g,
+];
+
+function isExternalSpecifier(specifier: string | undefined): specifier is string {
+  if (!specifier || specifier === "@pragma-sh/automations") return false;
+  if (/^[./]/.test(specifier)) return false;
+  return !builtins.has(specifier);
+}
+
+function bareImports(source: string): string[] {
+  const imports = new Set<string>();
+  for (const pattern of IMPORT_PATTERNS) {
+    for (const match of source.matchAll(pattern)) {
+      if (isExternalSpecifier(match[1])) imports.add(packageName(match[1]));
+    }
+  }
+  return [...imports];
+}
+
+async function ensureRuntimePackage(root: string): Promise<void> {
+  const pkgRoot = join(root, "node_modules", "@pragma", "automations");
+  await mkdir(pkgRoot, { recursive: true });
+  await writeFile(
+    join(pkgRoot, "package.json"),
+    JSON.stringify(
+      { name: "@pragma-sh/automations", type: "module", exports: { ".": "./index.ts" } },
+      null,
+      2,
+    ),
+  );
+  await writeFile(
+    join(pkgRoot, "index.ts"),
+    `export { defineAutomation };\n${defineAutomation.toString()}\n`,
+  );
+}
+
+async function ensurePackages(root: string, specifiers: string[]): Promise<void> {
+  await mkdir(root, { recursive: true });
+  await ensureRuntimePackage(root);
+  await writeFile(
+    join(root, "package.json"),
+    JSON.stringify({ type: "module", dependencies: {} }, null, 2),
+  );
+  const missing: string[] = [];
+  const checks = await Promise.all(
+    specifiers.map(async (specifier) => {
+      try {
+        await stat(join(root, "node_modules", specifier));
+        return null;
+      } catch {
+        return specifier;
+      }
+    }),
+  );
+  missing.push(...checks.filter((specifier): specifier is string => specifier !== null));
+  if (missing.length === 0) return;
+  const proc = Bun.spawn(["bun", "add", ...missing], {
+    cwd: root,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const code = await proc.exited;
+  if (code !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(`install failed for ${missing.join(", ")}: ${stderr.trim()}`);
+  }
+}
+
+function hasValidTrigger(definition: AutomationDefinition): boolean {
+  const trigger = definition.trigger;
+  return Boolean(trigger) && (trigger.type === "cron" || trigger.type === "event");
+}
+
+/** Returns the first failing validation message for a definition, or null when valid. */
+function automationProblem(definition: AutomationDefinition): string | null {
+  const checks: Array<[boolean, string]> = [
+    [definition.pragmaAutomation === true, "default export must use defineAutomation"],
+    [Boolean(definition.name.trim()), "automation name is required"],
+    [Boolean(definition.description.trim()), "automation description is required"],
+    [hasValidTrigger(definition), "automation trigger must be cron or event"],
+    [typeof definition.run === "function", "automation run must be a function"],
+  ];
+  return checks.find(([ok]) => !ok)?.[1] ?? null;
+}
+
+function validateAutomation(value: unknown): AutomationDefinition {
+  if (!value || typeof value !== "object") throw new Error("default export is not an automation");
+  const definition = value as AutomationDefinition;
+  const problem = automationProblem(definition);
+  if (problem) throw new Error(problem);
+  return definition;
+}
+
+async function copyEntry(command: LoadCommand, source: string, root: string): Promise<string> {
+  const entryRoot = join(root, "entries", command.id, command.sourceVersion ?? "current");
+  await mkdir(entryRoot, { recursive: true });
+  const extension = command.path.endsWith(".js") ? "js" : "ts";
+  const rewritten = source.replaceAll(
+    "@pragma-sh/automations",
+    pathToFileURL(join(root, "node_modules", "@pragma", "automations", "index.ts")).href,
+  );
+  const entry = join(entryRoot, `automation.${extension}`);
+  await writeFile(entry, rewritten);
+  return entry;
+}
+
+function contextFor(command: LoadCommand): AutomationContext {
+  const log = (level: "info" | "warn" | "error") => (message: string, data?: unknown) => {
+    emit({ type: "log", id: command.id, level, message, data });
+  };
+  return {
+    log: {
+      info: log("info"),
+      warn: log("warn"),
+      error: log("error"),
+    },
+    paths: {
+      project: command.root,
+      worktree: command.root,
+      global: command.scope === "global",
+    },
+    fs: {
+      find: (path, options) => findFiles(command.root, path, options),
+    },
+    git: {},
+  };
+}
+
+async function runAutomation(id: string, payload?: unknown): Promise<void> {
+  const automation = loaded.get(id);
+  if (!automation) throw new Error(`automation not loaded: ${id}`);
+  const ctx = contextFor(automation.command);
+  emit({ type: "status", id, status: "running" });
+  try {
+    await automation.definition.run(ctx, payload);
+    emit({ type: "status", id, status: "idle" });
+  } catch (error) {
+    emitError(id, error);
+  }
+}
+
+async function unload(id: string): Promise<void> {
+  const automation = loaded.get(id);
+  if (!automation) return;
+  automation.dispose?.();
+  loaded.delete(id);
+  emit({ type: "unloaded", id });
+}
+
+async function load(command: LoadCommand): Promise<void> {
+  await unload(command.id);
+  const source = await readFile(command.path, "utf8");
+  const root = cacheDir();
+  await ensurePackages(root, bareImports(source));
+  const entry = await copyEntry(command, source, root);
+  const imported = (await import(`${pathToFileURL(entry).href}?v=${Date.now()}`)) as {
+    default?: unknown;
+  };
+  const definition = validateAutomation(imported.default);
+  const loadedAutomation: LoadedAutomation = { command, definition };
+  loaded.set(command.id, loadedAutomation);
+  emit({
+    type: "loaded",
+    id: command.id,
+    name: definition.name,
+    description: definition.description,
+    triggerKind: definition.trigger.type,
+    schedule: definition.trigger.type === "cron" ? definition.trigger.schedule : null,
+  });
+  if (definition.trigger.type === "event") {
+    const ctx = contextFor(command);
+    const dispose = await definition.trigger.listen(ctx, (payload?: unknown) => {
+      void runAutomation(command.id, payload);
+    });
+    if (typeof dispose === "function") loadedAutomation.dispose = dispose;
+  }
+  emit({ type: "status", id: command.id, status: "idle" });
+}
+
+async function reload(id: string): Promise<void> {
+  const existing = loaded.get(id);
+  if (!existing) throw new Error(`automation not loaded: ${id}`);
+  await load(existing.command);
+}
+
+async function handle(command: Command): Promise<void> {
+  switch (command.type) {
+    case "load":
+      return load(command);
+    case "unload":
+      return unload(command.id);
+    case "reload":
+      return reload(command.id);
+    default:
+      return runAutomation(command.id);
+  }
+}
+
+class StdinLines {
+  constructor() {
+    readStdinLines(
+      (line) => void this.dispatch(line),
+      () => this.shutdown(),
+    );
+  }
+
+  private shutdown(): void {
+    // The server owns this sidecar through its stdin pipe. Parent death closes
+    // the pipe even after SIGKILL, so release automation-created listeners and
+    // timers before forcing the Bun process to leave no orphan behind.
+    for (const automation of loaded.values()) {
+      try {
+        automation.dispose?.();
+      } catch {
+        // stdout commonly closes with stdin; cleanup remains best-effort and
+        // must not turn parent death into another uncaught-error write.
+      }
+    }
+    loaded.clear();
+    process.exit(0);
+  }
+
+  private async dispatch(line: string): Promise<void> {
+    let command: Command | undefined;
+    try {
+      command = JSON.parse(line) as Command;
+      await handle(command);
+    } catch (error) {
+      emitError(command?.id, error);
+    }
+  }
+}
+
+// Automation callbacks (e.g. timers inside event listeners) can reject outside
+// runAutomation's try/catch; report instead of letting the sidecar die.
+process.on("unhandledRejection", (error) => emitError(undefined, error));
+process.on("uncaughtException", (error) => emitError(undefined, error));
+
+await mkdir(dirname(cacheDir()), { recursive: true });
+const stdinLines = new StdinLines();
+void stdinLines;
+emit({ type: "ready" });
+process.stdin.resume();

package/src/find.ts

@@ -0,0 +1,168 @@
+import type { Dirent } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+
+/** Options accepted by `ctx.fs.find`. */
+export interface FindOptions {
+  name?: string;
+  minBytes?: number;
+}
+
+// Missing or unreadable paths (ENOENT, EPERM, …) are skipped, not fatal —
+// a watcher polling for a file that does not exist yet must not throw.
+async function statSafe(path: string): Promise<Awaited<ReturnType<typeof stat>> | null> {
+  try {
+    return await stat(path);
+  } catch {
+    return null;
+  }
+}
+
+async function readdirSafe(path: string): Promise<Dirent[]> {
+  try {
+    return await readdir(path, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Directories a project-scoped search must never descend into. They are
+ * machine-generated, enormous, and never what an automation is watching for —
+ * `.pragma` in particular holds `worktrees/`, which multiplies the whole tree
+ * by the number of worktrees.
+ */
+const FIND_SKIP_DIRS = new Set([
+  ".git",
+  ".pragma",
+  "node_modules",
+  "target",
+  "dist",
+  "build",
+  ".next",
+  ".turbo",
+  ".cache",
+  ".venv",
+]);
+
+/**
+ * Directories walked at once. The walk used to recurse with an unbounded
+ * `Promise.all` per directory, so a large tree opened thousands of concurrent
+ * handles and the sidecar died with `EMFILE: too many open files`.
+ */
+const FIND_CONCURRENCY = 8;
+
+/** Depth cap, so a pathological tree cannot turn a poll into an endless walk. */
+const FIND_MAX_DEPTH = 12;
+
+function fileMatches(path: string, size: number | bigint, options: FindOptions): boolean {
+  if (options.name !== undefined && basename(path) !== options.name) return false;
+  return options.minBytes === undefined || size >= options.minBytes;
+}
+
+/** True when `candidate` stays inside `root`. */
+function within(root: string, candidate: string): boolean {
+  const rel = relative(resolve(root), resolve(candidate));
+  return rel === "" || (!rel.startsWith("..") && !rel.startsWith("/"));
+}
+
+interface FindWaveResult {
+  files: string[];
+  directories: string[];
+}
+
+function inspectDirectory(path: string, entry: Dirent): FindWaveResult {
+  return {
+    files: [],
+    directories: FIND_SKIP_DIRS.has(entry.name) ? [] : [path],
+  };
+}
+
+async function inspectFile(
+  root: string,
+  path: string,
+  entry: Dirent,
+  options: FindOptions,
+): Promise<FindWaveResult> {
+  if (!entry.isFile() || (options.name !== undefined && entry.name !== options.name)) {
+    return { files: [], directories: [] };
+  }
+  if (options.minBytes === undefined) {
+    return { files: [relative(root, path)], directories: [] };
+  }
+  const info = await statSafe(path);
+  return {
+    files: info && fileMatches(path, info.size, options) ? [relative(root, path)] : [],
+    directories: [],
+  };
+}
+
+async function inspectEntry(
+  root: string,
+  directory: string,
+  entry: Dirent,
+  options: FindOptions,
+): Promise<FindWaveResult> {
+  const path = join(directory, entry.name);
+  if (entry.isSymbolicLink()) return { files: [], directories: [] };
+  return entry.isDirectory()
+    ? inspectDirectory(path, entry)
+    : inspectFile(root, path, entry, options);
+}
+
+async function inspectWave(
+  root: string,
+  wave: string[],
+  options: FindOptions,
+): Promise<FindWaveResult> {
+  const result: FindWaveResult = { files: [], directories: [] };
+  const listings = await Promise.all(wave.map((directory) => readdirSafe(directory)));
+  for (const [index, entries] of listings.entries()) {
+    const directory = wave[index];
+    if (directory === undefined) continue;
+    for (const entry of entries) {
+      // Serial stats keep descriptor use flat even inside a concurrent directory wave.
+      // eslint-disable-next-line no-await-in-loop
+      const inspected = await inspectEntry(root, directory, entry, options);
+      result.files.push(...inspected.files);
+      result.directories.push(...inspected.directories);
+    }
+  }
+  return result;
+}
+
+/**
+ * Lists files under `start`, relative to the automation `root`.
+ */
+export async function findFiles(
+  root: string,
+  start: string,
+  options: FindOptions = {},
+): Promise<string[]> {
+  const base = resolve(root, start);
+  if (!within(root, base)) throw new Error("path escapes automation root");
+  const result: string[] = [];
+  const baseInfo = await statSafe(base);
+  if (!baseInfo) return result;
+  if (!baseInfo.isDirectory()) {
+    if (fileMatches(base, baseInfo.size, options)) result.push(relative(root, base));
+    return result;
+  }
+
+  // Breadth-first with a fixed-width wave rather than recursive `Promise.all`:
+  // the number of directories open at once is bounded, so a big tree costs
+  // time instead of file descriptors.
+  let level: string[] = [base];
+  for (let depth = 0; depth < FIND_MAX_DEPTH && level.length > 0; depth += 1) {
+    const next: string[] = [];
+    for (let index = 0; index < level.length; index += FIND_CONCURRENCY) {
+      const wave = level.slice(index, index + FIND_CONCURRENCY);
+      // eslint-disable-next-line no-await-in-loop -- serialising the waves is the point: it is what bounds open file descriptors
+      const inspected = await inspectWave(root, wave, options);
+      result.push(...inspected.files);
+      next.push(...inspected.directories);
+    }
+    level = next;
+  }
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+export interface AutomationLogger {
+  info(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+}
+
+export interface AutomationFsClient {
+  find(path: string, options?: { name?: string; minBytes?: number }): Promise<string[]>;
+}
+
+export interface AutomationContext {
+  log: AutomationLogger;
+  paths: {
+    project: string;
+    worktree: string;
+    global: boolean;
+  };
+  fs: AutomationFsClient;
+  git: Record<string, never>;
+}
+
+export type AutomationTrigger =
+  | { type: "cron"; schedule: string }
+  | {
+      type: "event";
+      listen: (
+        ctx: AutomationContext,
+        fire: (payload?: unknown) => void,
+      ) => (() => void) | void | Promise<(() => void) | void>;
+    };
+
+export interface AutomationDefinition {
+  name: string;
+  description: string;
+  trigger: AutomationTrigger;
+  run: (ctx: AutomationContext, payload?: unknown) => void | Promise<void>;
+  readonly pragmaAutomation: true;
+}
+
+export interface DefineAutomationInput {
+  name: string;
+  description: string;
+  trigger: AutomationTrigger;
+  run: (ctx: AutomationContext, payload?: unknown) => void | Promise<void>;
+}
+
+/** Defines one Pragma automation. Export the returned value as the file default. */
+export function defineAutomation(definition: DefineAutomationInput): AutomationDefinition {
+  return { ...definition, pragmaAutomation: true };
+}