@vellumai/assistant 0.8.12 → 0.9.0-staging.2

package/src/workflows/library.test.ts

@@ -0,0 +1,134 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Silence the logger so a skipped-file warning doesn't spam the test output.
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+import { getWorkflow, listWorkflows } from "./library.js";
+
+// Each test points VELLUM_WORKSPACE_DIR at a fresh temp dir, so `getWorkspaceDir`
+// resolves there and saved workflows live at `<temp>/workflows/*.workflow.ts`.
+let workspaceDir: string;
+let prevOverride: string | undefined;
+
+beforeEach(() => {
+  workspaceDir = mkdtempSync(join(tmpdir(), "wf-library-"));
+  prevOverride = process.env.VELLUM_WORKSPACE_DIR;
+  process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+});
+
+afterEach(() => {
+  if (prevOverride === undefined) delete process.env.VELLUM_WORKSPACE_DIR;
+  else process.env.VELLUM_WORKSPACE_DIR = prevOverride;
+  rmSync(workspaceDir, { recursive: true, force: true });
+});
+
+/** Write `<workspace>/workflows/<file>` with `source` (creating the dir). */
+function writeWorkflow(file: string, source: string): void {
+  const dir = join(workspaceDir, "workflows");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, file), source, "utf8");
+}
+
+describe("listWorkflows", () => {
+  test("returns [] and does not create the dir when none exists", () => {
+    expect(listWorkflows()).toEqual([]);
+    // A second call still sees no dir — listing never creates it eagerly.
+    expect(getWorkflow("anything")).toBeNull();
+  });
+
+  test("lists workflows with a statically-extractable meta", () => {
+    writeWorkflow(
+      "digest.workflow.ts",
+      `export const meta = { name: "daily-digest", description: "Summarize the day" };\nreturn agent("go");`,
+    );
+    writeWorkflow(
+      "research.workflow.ts",
+      `export const meta = { name: "research", description: "Research a topic" };\nreturn agent("go");`,
+    );
+
+    const entries = listWorkflows().sort((a, b) =>
+      a.name.localeCompare(b.name),
+    );
+    expect(entries).toHaveLength(2);
+    expect(entries[0]).toMatchObject({
+      name: "daily-digest",
+      description: "Summarize the day",
+    });
+    expect(entries[0]!.path).toContain("digest.workflow.ts");
+    expect(entries[1]).toMatchObject({
+      name: "research",
+      description: "Research a topic",
+    });
+  });
+
+  test("ignores non-`.workflow.ts` files", () => {
+    writeWorkflow(
+      "real.workflow.ts",
+      `export const meta = { name: "real", description: "d" };\nreturn 1;`,
+    );
+    writeWorkflow(
+      "notes.ts",
+      `export const meta = { name: "x", description: "y" };`,
+    );
+    writeWorkflow("README.md", `# not a workflow`);
+
+    const entries = listWorkflows();
+    expect(entries.map((e) => e.name)).toEqual(["real"]);
+  });
+
+  test("skips a file whose meta is computed/non-literal (cannot be statically extracted)", () => {
+    writeWorkflow(
+      "ok.workflow.ts",
+      `export const meta = { name: "ok", description: "fine" };\nreturn 1;`,
+    );
+    // Computed meta: a call expression cannot be statically extracted and the
+    // file is skipped rather than failing the whole listing.
+    writeWorkflow(
+      "computed.workflow.ts",
+      `const make = () => ({ name: "nope", description: "d" });\nexport const meta = make();\nreturn 1;`,
+    );
+    // Missing meta entirely.
+    writeWorkflow("nometa.workflow.ts", `return agent("go");`);
+
+    const entries = listWorkflows();
+    expect(entries.map((e) => e.name)).toEqual(["ok"]);
+  });
+});
+
+describe("getWorkflow", () => {
+  test("resolves by meta.name", () => {
+    const source = `export const meta = { name: "daily-digest", description: "d" };\nreturn agent("go");`;
+    writeWorkflow("digest.workflow.ts", source);
+
+    const resolved = getWorkflow("daily-digest");
+    expect(resolved).not.toBeNull();
+    expect(resolved!.source).toBe(source);
+    expect(resolved!.path).toContain("digest.workflow.ts");
+  });
+
+  test("falls back to the filename base when no meta.name matches", () => {
+    // meta.name is "canonical" but the caller asks by the file base "byfile".
+    const source = `export const meta = { name: "canonical", description: "d" };\nreturn 1;`;
+    writeWorkflow("byfile.workflow.ts", source);
+
+    expect(getWorkflow("byfile")!.source).toBe(source);
+    // The canonical meta.name also resolves.
+    expect(getWorkflow("canonical")!.source).toBe(source);
+  });
+
+  test("returns null for an unknown name", () => {
+    writeWorkflow(
+      "real.workflow.ts",
+      `export const meta = { name: "real", description: "d" };\nreturn 1;`,
+    );
+    expect(getWorkflow("ghost")).toBeNull();
+  });
+});

package/src/workflows/library.ts

@@ -0,0 +1,124 @@
+/**
+ * Saved-workflow LIBRARY — named workflows the assistant can invoke by name and
+ * the scheduler can trigger.
+ *
+ * Saved workflows live at `<workspace>/workflows/*.workflow.ts`. Each file is a
+ * normal workflow script: a leading literal `export const meta = { name,
+ * description }` followed by the script body. The library only reads the STATIC
+ * `meta` (via {@link extractWorkflowMeta}, a pure-literal extractor that never
+ * executes the untrusted source — only the QuickJS sandbox may run it) and the
+ * raw source. Resolution to an actual run goes through {@link executeWorkflow} /
+ * {@link WorkflowRunManager}, which run the source in the sandbox.
+ *
+ * The directory is read lazily and is NOT created eagerly: if it does not exist,
+ * {@link listWorkflows} returns `[]` and {@link getWorkflow} returns `null`.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { getLogger } from "../util/logger.js";
+import { getWorkspaceDir } from "../util/platform.js";
+import { extractWorkflowMeta } from "./engine.js";
+
+const log = getLogger("workflow-library");
+
+/** File suffix every saved workflow uses. */
+const WORKFLOW_SUFFIX = ".workflow.ts";
+
+/** A saved workflow surfaced by {@link listWorkflows}. */
+export interface SavedWorkflowEntry {
+  /** The workflow's `meta.name`. */
+  name: string;
+  /** The workflow's `meta.description`. */
+  description: string;
+  /** Absolute path to the `*.workflow.ts` file. */
+  path: string;
+}
+
+/** The source + path of a resolved saved workflow. */
+export interface SavedWorkflowSource {
+  /** The raw script source (TS). */
+  source: string;
+  /** Absolute path to the `*.workflow.ts` file. */
+  path: string;
+}
+
+/** Absolute path to the saved-workflows directory (`<workspace>/workflows`). */
+function workflowsDir(): string {
+  return join(getWorkspaceDir(), "workflows");
+}
+
+/** The filename (sans `.workflow.ts`) for `<workspace>/workflows/<base>.workflow.ts`. */
+function fileBaseName(file: string): string {
+  return file.slice(0, -WORKFLOW_SUFFIX.length);
+}
+
+/** A `*.workflow.ts` file read off disk, before meta extraction. */
+interface RawWorkflowFile {
+  file: string;
+  path: string;
+  source: string;
+}
+
+/**
+ * Yield every readable `*.workflow.ts` file in the workflows directory (each read
+ * once). Returns nothing if the directory does not exist — it is never created.
+ * An unreadable file is skipped with a logged warning.
+ */
+function* readWorkflowFiles(): Generator<RawWorkflowFile> {
+  const dir = workflowsDir();
+  if (!existsSync(dir)) return;
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith(WORKFLOW_SUFFIX)) continue;
+    const path = join(dir, file);
+    try {
+      yield { file, path, source: readFileSync(path, "utf8") };
+    } catch (err) {
+      log.warn({ err, path }, "Failed to read saved workflow; skipping");
+    }
+  }
+}
+
+/**
+ * List every saved workflow with a statically-extractable `meta`. A file whose
+ * `meta` cannot be statically extracted (computed/missing/malformed) is SKIPPED
+ * with a logged warning rather than failing the whole listing.
+ */
+export function listWorkflows(): SavedWorkflowEntry[] {
+  const entries: SavedWorkflowEntry[] = [];
+  for (const { path, source } of readWorkflowFiles()) {
+    try {
+      const meta = extractWorkflowMeta(source);
+      entries.push({ name: meta.name, description: meta.description, path });
+    } catch (err) {
+      log.warn(
+        { err, path },
+        "Saved workflow has no statically-extractable meta; skipping",
+      );
+    }
+  }
+  return entries;
+}
+
+/**
+ * Resolve a saved workflow by name. Matches against the workflow's `meta.name`
+ * first, then falls back to the filename base (`<base>.workflow.ts`). Returns the
+ * source + path, or `null` if no saved workflow matches.
+ */
+export function getWorkflow(name: string): SavedWorkflowSource | null {
+  let fileMatch: SavedWorkflowSource | null = null;
+  for (const { file, path, source } of readWorkflowFiles()) {
+    // Prefer a `meta.name` match — it is the canonical identity.
+    try {
+      if (extractWorkflowMeta(source).name === name) return { source, path };
+    } catch {
+      // Fall through: a file with non-extractable meta can still match by name.
+    }
+    // Remember the first filename-base match as a fallback.
+    if (fileMatch === null && fileBaseName(file) === name) {
+      fileMatch = { source, path };
+    }
+  }
+  return fileMatch;
+}