@scardis/omnifocus-mcp 0.1.0

package/test/integration/listTasksFiltered.int.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { runSnippet } from "../../src/runtime/bridge.js";
+import {
+  createTestFolder,
+  cleanupTestFolder,
+  createTestProject,
+  createTestTag,
+  deleteTestTag,
+  type TestFixture,
+} from "./fixtures.js";
+import { TaskSummary } from "../../src/schemas/index.js";
+import { z } from "zod";
+
+const TaskSummaryArray = z.array(TaskSummary);
+
+describe("list_tasks filtering (integration)", () => {
+  let fixture: TestFixture;
+  let projectId: string;
+  let tagId: string;
+
+  beforeAll(async () => {
+    fixture = await createTestFolder();
+    projectId = await createTestProject(fixture.folderId, "FilterTest Project");
+    tagId = await createTestTag(`__mcp_filter_tag_${Date.now()}__`);
+
+    // Create tasks with various properties inside the project
+    // flagged task
+    await runSnippet("create_task", {
+      name: "Flagged Task",
+      projectId,
+      flagged: true,
+    });
+    // task with tag and due date in the past
+    await runSnippet("create_task", {
+      name: "Tagged Past Due Task",
+      projectId,
+      tagIds: [tagId],
+      dueDate: "2020-01-01T00:00:00.000Z",
+    });
+    // task with due date far in future
+    await runSnippet("create_task", {
+      name: "Future Due Task",
+      projectId,
+      dueDate: "2099-12-31T23:59:59.000Z",
+    });
+    // plain task (no flags, no tags, no due date)
+    await runSnippet("create_task", { name: "Plain Task", projectId });
+  });
+
+  afterAll(async () => {
+    await deleteTestTag(tagId);
+    await cleanupTestFolder(fixture.folderId);
+  });
+
+  it("returns dueDate and tagIds on each task summary", async () => {
+    const raw = await runSnippet("list_tasks", { scope: { projectId } });
+    const tasks = TaskSummaryArray.parse(raw);
+    expect(tasks.length).toBeGreaterThan(0);
+    // Every task must have these fields (added to TaskSummary)
+    for (const t of tasks) {
+      expect(t).toHaveProperty("dueDate");
+      expect(t).toHaveProperty("tagIds");
+      expect(Array.isArray(t.tagIds)).toBe(true);
+    }
+  });
+
+  it("enriched summary includes correct dueDate and tagIds", async () => {
+    const raw = await runSnippet("list_tasks", { scope: { projectId } });
+    const tasks = TaskSummaryArray.parse(raw);
+    const tagged = tasks.find((t) => t.name === "Tagged Past Due Task");
+    expect(tagged).toBeDefined();
+    expect(tagged!.dueDate).toBe("2020-01-01T00:00:00.000Z");
+    expect(tagged!.tagIds).toContain(tagId);
+  });
+
+  it("default excludes complete and dropped tasks", async () => {
+    // Complete one task then check it's absent by default
+    const raw1 = await runSnippet("list_tasks", { scope: { projectId } });
+    const tasks1 = TaskSummaryArray.parse(raw1);
+    const plain = tasks1.find((t) => t.name === "Plain Task");
+    expect(plain).toBeDefined();
+
+    await runSnippet("complete_task", { id: plain!.id });
+
+    const raw2 = await runSnippet("list_tasks", { scope: { projectId } });
+    const tasks2 = TaskSummaryArray.parse(raw2);
+    expect(tasks2.find((t) => t.id === plain!.id)).toBeUndefined();
+  });
+
+  it("explicit status filter retrieves complete tasks", async () => {
+    const raw = await runSnippet("list_tasks", {
+      scope: { projectId },
+      filter: { status: ["complete"] },
+    });
+    const tasks = TaskSummaryArray.parse(raw);
+    expect(tasks.some((t) => t.name === "Plain Task")).toBe(true);
+    expect(tasks.every((t) => t.status === "complete")).toBe(true);
+  });
+
+  it("flagged filter returns only flagged tasks", async () => {
+    const raw = await runSnippet("list_tasks", {
+      scope: { projectId },
+      filter: { flagged: true },
+    });
+    const tasks = TaskSummaryArray.parse(raw);
+    expect(tasks.length).toBeGreaterThan(0);
+    expect(tasks.every((t) => t.flagged)).toBe(true);
+    expect(tasks.some((t) => t.name === "Flagged Task")).toBe(true);
+  });
+
+  it("tagId filter returns only tasks with that tag", async () => {
+    const raw = await runSnippet("list_tasks", {
+      scope: { projectId },
+      filter: { tagId },
+    });
+    const tasks = TaskSummaryArray.parse(raw);
+    expect(tasks.length).toBeGreaterThan(0);
+    expect(tasks.every((t) => t.tagIds.includes(tagId))).toBe(true);
+    expect(tasks.some((t) => t.name === "Tagged Past Due Task")).toBe(true);
+  });
+
+  it("dueBeforeDate filter returns tasks due on or before the date", async () => {
+    // Cutoff in 2021 — should match the 2020 task, not the 2099 task
+    const raw = await runSnippet("list_tasks", {
+      scope: { projectId },
+      filter: { dueBeforeDate: "2021-01-01T00:00:00.000Z" },
+    });
+    const tasks = TaskSummaryArray.parse(raw);
+    expect(tasks.some((t) => t.name === "Tagged Past Due Task")).toBe(true);
+    expect(tasks.some((t) => t.name === "Future Due Task")).toBe(false);
+  });
+
+  it("limit caps the number of returned tasks", async () => {
+    const raw = await runSnippet("list_tasks", {
+      scope: { projectId },
+      limit: 1,
+    });
+    const tasks = TaskSummaryArray.parse(raw);
+    expect(tasks.length).toBeLessThanOrEqual(1);
+  });
+});

package/test/integration/moveProject.int.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { runSnippet } from "../../src/runtime/bridge.js";
+import { createTestFolder, cleanupTestFolder, createTestProject, type TestFixture } from "./fixtures.js";
+import { ProjectSummary } from "../../src/schemas/index.js";
+
+describe("move_project (integration)", () => {
+  let fixtureA: TestFixture;
+  let fixtureB: TestFixture;
+  let projectId: string;
+
+  beforeAll(async () => {
+    fixtureA = await createTestFolder();
+    fixtureB = await createTestFolder();
+    projectId = await createTestProject(fixtureA.folderId, "__mcp_move_project__");
+  });
+
+  afterAll(async () => {
+    // Delete the project explicitly — it may have been moved to top level (outside any fixture folder)
+    try {
+      await runSnippet("delete_project", { id: projectId });
+    } catch (_) { /* already gone */ }
+    await cleanupTestFolder(fixtureA.folderId);
+    await cleanupTestFolder(fixtureB.folderId);
+  });
+
+  it("moves project to a different folder", async () => {
+    const raw = await runSnippet("move_project", { id: projectId, folderId: fixtureB.folderId });
+    const result = ProjectSummary.parse(raw);
+    expect(result.id).toBe(projectId);
+    expect(result.folderId).toBe(fixtureB.folderId);
+  });
+
+  it("moves project to top level (folderId null)", async () => {
+    const raw = await runSnippet("move_project", { id: projectId, folderId: null });
+    const result = ProjectSummary.parse(raw);
+    expect(result.id).toBe(projectId);
+    expect(result.folderId).toBeNull();
+  });
+
+  it("non-existent project ID returns NotFoundError", async () => {
+    await expect(
+      runSnippet("move_project", { id: "nonexistent-project-xyz", folderId: fixtureA.folderId })
+    ).rejects.toSatisfy((e: unknown) => {
+      const err = e as Record<string, unknown>;
+      return err.name === "ExecutionError" && err.errorName === "NotFoundError";
+    });
+  });
+
+  it("non-existent folder ID returns NotFoundError", async () => {
+    await expect(
+      runSnippet("move_project", { id: projectId, folderId: "nonexistent-folder-xyz" })
+    ).rejects.toSatisfy((e: unknown) => {
+      const err = e as Record<string, unknown>;
+      return err.name === "ExecutionError" && err.errorName === "NotFoundError";
+    });
+  });
+});

package/test/integration/moveTask.int.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { runSnippet } from "../../src/runtime/bridge.js";
+import { createTestFolder, cleanupTestFolder, createTestProject, type TestFixture } from "./fixtures.js";
+import { TaskSummary } from "../../src/schemas/index.js";
+
+describe("move_task (integration)", () => {
+  let fixture: TestFixture;
+  let projectAId: string;
+  let projectBId: string;
+  let taskId: string;
+  let parentTaskId: string;
+
+  beforeAll(async () => {
+    fixture = await createTestFolder();
+    projectAId = await createTestProject(fixture.folderId, "__mcp_move_proj_a__");
+    projectBId = await createTestProject(fixture.folderId, "__mcp_move_proj_b__");
+
+    // Create a task in project A
+    const taskRaw = await runSnippet("create_task", {
+      name: "__mcp_move_task__",
+      projectId: projectAId,
+    });
+    taskId = (taskRaw as { id: string }).id;
+
+    // Create a parent task in project B
+    const parentRaw = await runSnippet("create_task", {
+      name: "__mcp_parent_task__",
+      projectId: projectBId,
+    });
+    parentTaskId = (parentRaw as { id: string }).id;
+  });
+
+  afterAll(async () => {
+    await cleanupTestFolder(fixture.folderId);
+  });
+
+  it("moves task to a different project", async () => {
+    const raw = await runSnippet("move_task", { id: taskId, projectId: projectBId });
+    const result = TaskSummary.parse(raw);
+    expect(result.id).toBe(taskId);
+    expect(result.containerId).toBe(projectBId);
+    expect(result.containerType).toBe("project");
+  });
+
+  it("makes task a subtask of another task", async () => {
+    const raw = await runSnippet("move_task", { id: taskId, parentTaskId });
+    const result = TaskSummary.parse(raw);
+    expect(result.id).toBe(taskId);
+    expect(result.containerId).toBe(parentTaskId);
+    expect(result.containerType).toBe("task");
+  });
+
+  it("non-existent task ID returns NotFoundError", async () => {
+    await expect(
+      runSnippet("move_task", { id: "nonexistent-task-xyz", projectId: projectAId })
+    ).rejects.toSatisfy((e: unknown) => {
+      const err = e as Record<string, unknown>;
+      return err.name === "ExecutionError" && err.errorName === "NotFoundError";
+    });
+  });
+});

package/test/integration/plannedDate.int.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { runSnippet } from "../../src/runtime/bridge.js";
+import { createTestFolder, cleanupTestFolder, createTestProject, type TestFixture } from "./fixtures.js";
+import { TaskDetail } from "../../src/schemas/index.js";
+
+describe("plannedDate (integration)", () => {
+  let fixture: TestFixture;
+  let projectId: string;
+
+  beforeAll(async () => {
+    fixture = await createTestFolder();
+    projectId = await createTestProject(fixture.folderId, "__mcp_planned_date_test__");
+  });
+
+  afterAll(async () => {
+    await cleanupTestFolder(fixture.folderId);
+  });
+
+  it("creates task with plannedDate and get_task returns it", async () => {
+    const raw = await runSnippet("create_task", {
+      name: "__mcp_planned_create__",
+      projectId,
+      plannedDate: "2026-04-15T09:00:00.000Z",
+    });
+    const task = TaskDetail.parse(raw);
+    expect(task.plannedDate).not.toBeNull();
+    expect(task.plannedDate).toContain("2026-04-15");
+
+    const fetched = TaskDetail.parse(await runSnippet("get_task", { id: task.id }));
+    expect(fetched.plannedDate).toContain("2026-04-15");
+  });
+
+  it("edits task to set plannedDate", async () => {
+    const created = TaskDetail.parse(
+      await runSnippet("create_task", { name: "__mcp_planned_edit__", projectId })
+    );
+    expect(created.plannedDate).toBeNull();
+
+    const edited = TaskDetail.parse(
+      await runSnippet("edit_task", { id: created.id, plannedDate: "2026-05-01T10:00:00.000Z" })
+    );
+    expect(edited.plannedDate).toContain("2026-05-01");
+  });
+
+  it("clears plannedDate via edit with null", async () => {
+    const created = TaskDetail.parse(
+      await runSnippet("create_task", {
+        name: "__mcp_planned_clear__",
+        projectId,
+        plannedDate: "2026-04-20T08:00:00.000Z",
+      })
+    );
+    expect(created.plannedDate).not.toBeNull();
+
+    const cleared = TaskDetail.parse(
+      await runSnippet("edit_task", { id: created.id, plannedDate: null })
+    );
+    expect(cleared.plannedDate).toBeNull();
+
+    const fetched = TaskDetail.parse(await runSnippet("get_task", { id: created.id }));
+    expect(fetched.plannedDate).toBeNull();
+  });
+
+  it("task without plannedDate returns null (backward compat)", async () => {
+    const raw = await runSnippet("create_task", {
+      name: "__mcp_planned_none__",
+      projectId,
+    });
+    const task = TaskDetail.parse(raw);
+    expect(task.plannedDate).toBeNull();
+  });
+});

package/test/integration/preflight.ts

@@ -0,0 +1,60 @@
+import { runSnippet } from "../../src/runtime/index.js";
+
+const SYNC_CHECK_SNIPPET_NAME = "check_sync_enabled";
+
+// Inline snippet: no src/snippets file needed for this one-off preflight check.
+// We run it via the bridge directly using a temporary approach.
+async function isSyncEnabled(): Promise<boolean> {
+  try {
+    // OmniJS: check if the database has sync settings configured
+    const { spawnSync } = await import("child_process");
+    const script = `
+      (function() {
+        try {
+          var app = Application('OmniFocus');
+          app.includeStandardAdditions = true;
+          var snippet = "(function() { try { var db = document; var sync = db.willSynchronize !== undefined ? db.willSynchronize : false; return JSON.stringify({ok:true,data:{syncEnabled:sync}}); } catch(e) { return JSON.stringify({ok:true,data:{syncEnabled:false}}); } })()";
+          var result = app.evaluateJavascript(snippet);
+          $.NSFileHandle.fileHandleWithStandardOutput.writeData(
+            $.NSString.alloc.initWithString(result + '\\n').dataUsingEncoding($.NSUTF8StringEncoding)
+          );
+        } catch(e) {
+          $.NSFileHandle.fileHandleWithStandardOutput.writeData(
+            $.NSString.alloc.initWithString(JSON.stringify({ok:true,data:{syncEnabled:false}}) + '\\n').dataUsingEncoding($.NSUTF8StringEncoding)
+          );
+        }
+      })();
+    `;
+    const result = spawnSync("osascript", ["-l", "JavaScript"], {
+      input: script,
+      encoding: "utf-8",
+      timeout: 10_000,
+    });
+    if (result.stdout) {
+      const parsed = JSON.parse(result.stdout.trim()) as {
+        ok: boolean;
+        data: { syncEnabled: boolean };
+      };
+      if (parsed.ok) return parsed.data.syncEnabled;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export async function setup(): Promise<void> {
+  if (process.platform !== "darwin") {
+    throw new Error(
+      "Integration tests require macOS (OmniFocus + osascript unavailable)"
+    );
+  }
+
+  const syncEnabled = await isSyncEnabled();
+  if (syncEnabled && !process.env["MCP_TEST_ALLOW_SYNC"]) {
+    throw new Error(
+      "OmniFocus sync is enabled. Integration tests would propagate fixture folders to other devices.\n" +
+        "Set MCP_TEST_ALLOW_SYNC=1 to run anyway (fixtures will sync), or disable sync first."
+    );
+  }
+}

package/test/integration/resolveName.int.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { runSnippet } from "../../src/runtime/bridge.js";
+import { createTestFolder, cleanupTestFolder, type TestFixture } from "./fixtures.js";
+import { z } from "zod";
+import { ResolveCandidate } from "../../src/schemas/index.js";
+
+/**
+ * Integration test: resolve_name
+ *
+ * Creates two projects with identical names under different folders.
+ * Asserts resolve_name returns both candidates with distinct paths,
+ * never silently picking one.
+ */
+describe("resolve_name (integration)", () => {
+  let fixture1: TestFixture;
+  let fixture2: TestFixture;
+  const DUPE_NAME = `DuplicateProject_${Date.now()}`;
+
+  beforeAll(async () => {
+    fixture1 = await createTestFolder();
+    fixture2 = await createTestFolder();
+
+    const { spawnSync } = await import("child_process");
+
+    for (const folderId of [fixture1.folderId, fixture2.folderId]) {
+      const createSnippet = `(() => {
+        var folder = flattenedFolders.find(function(f){ return f.id.primaryKey === ${JSON.stringify(folderId)}; });
+        if (!folder) throw new Error("Fixture folder not found: " + ${JSON.stringify(folderId)});
+        var p = new Project(${JSON.stringify(DUPE_NAME)}, folder);
+        return JSON.stringify({ok:true,data:{id:p.id.primaryKey}});
+      })()`;
+      const script = `
+        (function() {
+          var app = Application('OmniFocus');
+          app.includeStandardAdditions = true;
+          try {
+            var r = app.evaluateJavascript(${JSON.stringify(createSnippet)});
+            $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(r+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+          } catch(e) {
+            $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(JSON.stringify({ok:false,error:{name:e.name,message:e.message}})+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+          }
+        })();
+      `;
+      const result = spawnSync("osascript", ["-l", "JavaScript"], {
+        input: script, encoding: "utf-8", timeout: 15_000,
+      });
+      const line = (result.stdout || "").split("\n").find((l) => l.trim().startsWith("{"));
+      if (!line) throw new Error(`Could not create fixture project in ${folderId}`);
+      const parsed = JSON.parse(line) as { ok: boolean; error?: { message: string } };
+      if (!parsed.ok) throw new Error(`Create project failed: ${parsed.error?.message}`);
+    }
+  });
+
+  afterAll(async () => {
+    await Promise.all([
+      cleanupTestFolder(fixture1.folderId),
+      cleanupTestFolder(fixture2.folderId),
+    ]);
+  });
+
+  it("returns both candidates when duplicate project names exist under different folders", async () => {
+    const raw = await runSnippet("resolve_name", {
+      type: "project",
+      query: DUPE_NAME,
+      scope: null,
+    });
+    const candidates = z.array(ResolveCandidate).parse(raw);
+    const mine = candidates.filter((c) => c.name === DUPE_NAME);
+    expect(mine.length).toBeGreaterThanOrEqual(2);
+
+    // Each candidate must have a distinct path
+    const paths = mine.map((c) => c.path);
+    const unique = new Set(paths);
+    expect(unique.size).toBe(mine.length);
+  });
+
+  it("returns empty array for a name that matches nothing", async () => {
+    const raw = await runSnippet("resolve_name", {
+      type: "project",
+      query: `__nonexistent_${Date.now()}__`,
+      scope: null,
+    });
+    const candidates = z.array(ResolveCandidate).parse(raw);
+    expect(candidates).toHaveLength(0);
+  });
+});

package/test/integration/taskRecurrence.int.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { runSnippet } from "../../src/runtime/bridge.js";
+import { createTestFolder, cleanupTestFolder, createTestProject, type TestFixture } from "./fixtures.js";
+import { TaskDetail } from "../../src/schemas/index.js";
+
+describe("task recurrence (integration)", () => {
+  let fixture: TestFixture;
+  let projectId: string;
+
+  beforeAll(async () => {
+    fixture = await createTestFolder();
+    projectId = await createTestProject(fixture.folderId, "__mcp_recurrence_test__");
+  });
+
+  afterAll(async () => {
+    await cleanupTestFolder(fixture.folderId);
+  });
+
+  it("creates task with daily repetition and get_task returns it", async () => {
+    const raw = await runSnippet("create_task", {
+      name: "__mcp_daily_task__",
+      projectId,
+      repetitionRule: { frequency: "daily", interval: 1, method: "fixed" },
+    });
+    const task = TaskDetail.parse(raw);
+    expect(task.repetitionRule).not.toBeNull();
+    expect(task.repetitionRule?.frequency).toBe("daily");
+    expect(task.repetitionRule?.interval).toBe(1);
+    expect(task.repetitionRule?.method).toBe("fixed");
+
+    const getraw = await runSnippet("get_task", { id: task.id });
+    const fetched = TaskDetail.parse(getraw);
+    expect(fetched.repetitionRule?.frequency).toBe("daily");
+    expect(fetched.repetitionRule?.method).toBe("fixed");
+  });
+
+  it("creates task with weekly repetition on Mon/Wed/Fri", async () => {
+    const raw = await runSnippet("create_task", {
+      name: "__mcp_weekly_task__",
+      projectId,
+      repetitionRule: {
+        frequency: "weekly",
+        interval: 1,
+        daysOfWeek: ["monday", "wednesday", "friday"],
+        method: "start",
+      },
+    });
+    const task = TaskDetail.parse(raw);
+    expect(task.repetitionRule?.frequency).toBe("weekly");
+    expect(task.repetitionRule?.daysOfWeek).toEqual(
+      expect.arrayContaining(["monday", "wednesday", "friday"])
+    );
+    expect(task.repetitionRule?.daysOfWeek).toHaveLength(3);
+    expect(task.repetitionRule?.method).toBe("start");
+  });
+
+  it("edits existing task to add monthly repetition", async () => {
+    const created = await runSnippet("create_task", {
+      name: "__mcp_edit_recur_task__",
+      projectId,
+    });
+    const task = TaskDetail.parse(created);
+    expect(task.repetitionRule).toBeNull();
+
+    const edited = await runSnippet("edit_task", {
+      id: task.id,
+      repetitionRule: { frequency: "monthly", interval: 1, method: "dueDate" },
+    });
+    const updated = TaskDetail.parse(edited);
+    expect(updated.repetitionRule?.frequency).toBe("monthly");
+    expect(updated.repetitionRule?.interval).toBe(1);
+    expect(updated.repetitionRule?.method).toBe("dueDate");
+  });
+
+  it("clears repetition via edit with null", async () => {
+    const created = await runSnippet("create_task", {
+      name: "__mcp_clear_recur_task__",
+      projectId,
+      repetitionRule: { frequency: "daily", interval: 1, method: "fixed" },
+    });
+    const task = TaskDetail.parse(created);
+    expect(task.repetitionRule).not.toBeNull();
+
+    const cleared = await runSnippet("edit_task", {
+      id: task.id,
+      repetitionRule: null,
+    });
+    const updated = TaskDetail.parse(cleared);
+    expect(updated.repetitionRule).toBeNull();
+
+    const fetched = TaskDetail.parse(await runSnippet("get_task", { id: task.id }));
+    expect(fetched.repetitionRule).toBeNull();
+  });
+
+  it("task created without repetitionRule returns repetitionRule: null", async () => {
+    const raw = await runSnippet("create_task", {
+      name: "__mcp_no_recur_task__",
+      projectId,
+    });
+    const task = TaskDetail.parse(raw);
+    expect(task.repetitionRule).toBeNull();
+
+    const fetched = TaskDetail.parse(await runSnippet("get_task", { id: task.id }));
+    expect(fetched.repetitionRule).toBeNull();
+  });
+});

package/test/unit/bridge.injection.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from "vitest";
+
+/**
+ * Proves Design Decision 2:
+ * JSON.stringify(args) produces a valid JS expression for any args value,
+ * including apostrophes, quotes, backslashes, newlines, and unicode.
+ *
+ * We test the injection logic directly without hitting the bridge or OmniFocus.
+ */
+
+const TRICKY_ARGS = {
+  name: "Finn's \"birthday\" 🎯",
+  note: "line1\nline2\ttabbed",
+  path: "Work ▸ Clients ▸ Acme",
+  backslash: "C:\\Users\\test",
+  unicode: "\u2603 snowman \u0000 null",
+};
+
+function injectArgs(template: string, args: unknown): string {
+  return template.replace("__ARGS__", JSON.stringify(args));
+}
+
+describe("argument injection safety", () => {
+  it("produces valid JavaScript for tricky string values", () => {
+    const template = "(() => { const args = __ARGS__; return args; })()";
+    const injected = injectArgs(template, TRICKY_ARGS);
+    // new Function wraps the body in a function; we eval the IIFE directly
+    let result: unknown;
+    expect(() => {
+      result = new Function(`return ${injected}`)();
+    }).not.toThrow();
+    expect(result).toEqual(TRICKY_ARGS);
+  });
+
+  it("recovers apostrophes exactly", () => {
+    const template = "(() => { const args = __ARGS__; return args; })()";
+    const args = { name: "it's a test's value" };
+    const injected = injectArgs(template, args);
+    const result = new Function(`return ${injected}`)() as typeof args;
+    expect(result.name).toBe("it's a test's value");
+  });
+
+  it("recovers double quotes exactly", () => {
+    const template = "(() => { const args = __ARGS__; return args; })()";
+    const args = { name: 'She said "hello"' };
+    const injected = injectArgs(template, args);
+    const result = new Function(`return ${injected}`)() as typeof args;
+    expect(result.name).toBe('She said "hello"');
+  });
+
+  it("recovers newlines exactly", () => {
+    const template = "(() => { const args = __ARGS__; return args; })()";
+    const args = { note: "line1\nline2\nline3" };
+    const injected = injectArgs(template, args);
+    const result = new Function(`return ${injected}`)() as typeof args;
+    expect(result.note).toBe("line1\nline2\nline3");
+  });
+
+  it("recovers unicode exactly", () => {
+    const template = "(() => { const args = __ARGS__; return args; })()";
+    const args = { symbol: "▸ ★ 🎉" };
+    const injected = injectArgs(template, args);
+    const result = new Function(`return ${injected}`)() as typeof args;
+    expect(result.symbol).toBe("▸ ★ 🎉");
+  });
+});