@wenathlan/devthink 2.0.13 → 2.0.15

package/tests/memorycare.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, it } from "vitest";
+import {
+  attachprovenance,
+  auditexportof,
+  bytesreclaimed,
+  cleanupbatch,
+  derivekey,
+  decryptvalue,
+  encryptvalue,
+  expireditems,
+  expiryof,
+  exportchunks,
+  exportready,
+  issensitiveclass,
+  matchingrule,
+  memoryitemof,
+  migrateitem,
+  purgeitems,
+  provenanceof,
+  quotareportof,
+  rankedcandidates,
+  stepsummaryfor,
+} from "../memory.js";
+import {
+  auditexportgate,
+  encryptionsecretgate,
+  encryptmemorygate,
+  expirygate,
+  exportprovenancegate,
+  quotacleanupgate,
+} from "../policy.js";
+import { auditexportreport } from "../protocol.js";
+import { sessionmemory } from "../memory.js";
+import type { purgeoutcome } from "../memory.js";
+import type { expiryrule, memoryitem, toolstep } from "../types.js";
+
+const now = 1_800_000_000_000;
+const origin = "https://example.com";
+const steps: toolstep[] = [
+  { id: "s1", kind: "click", target: "#submit", summary: "Click the reviewed submit control.", risk: "sensitive" },
+  { id: "s2", kind: "observe", summary: "Read the page.", risk: "read" },
+];
+
+function itemof(key: string, memoryclass?: string, capturedat = now, expiresat?: number): memoryitem {
+  return memoryitemof({
+    key,
+    value: { text: `value of ${key}` },
+    provenance: provenanceof({ origin, runid: "run1", stepid: "s1", now: capturedat }),
+    ...(memoryclass !== undefined ? { memoryclass } : {}),
+    ...(expiresat !== undefined ? { expiresat } : {}),
+  });
+}
+
+class fakeadapter {
+  private readonly data = new Map<string, unknown>();
+  async get<T>(key: string): Promise<T | undefined> {
+    return this.data.get(key) as T | undefined;
+  }
+  async set<T>(key: string, value: T): Promise<void> {
+    this.data.set(key, value);
+  }
+}
+
+describe("provenance", () => {
+  it("attaches a provenance record to every stored memory item and resolves its originating step summary", () => {
+    const provenance = provenanceof({ origin, runid: "run1", stepid: "s1", now });
+    expect(provenance).toEqual({ origin, runid: "run1", stepid: "s1", capturedat: now });
+    expect(() => provenanceof({ origin: " ", runid: "run1", stepid: "s1", now })).toThrow(/origin/i);
+    expect(() => provenanceof({ origin, runid: " ", stepid: "s1", now })).toThrow(/run id/i);
+    expect(() => provenanceof({ origin, runid: "run1", stepid: " ", now })).toThrow(/step id/i);
+    const item = itemof("note:1", "general");
+    expect(item.provenance).toEqual(provenance);
+    expect(() => memoryitemof({ key: " ", value: 1, provenance })).toThrow(/key/i);
+    expect(attachprovenance(item, provenance).provenance).toEqual(provenance);
+    expect(stepsummaryfor(item, steps)).toBe("Click the reviewed submit control.");
+    const unknown = { ...item, provenance: { ...provenance, stepid: "sX" } };
+    expect(stepsummaryfor(unknown, steps)).toMatch(/no longer carries/i);
+    expect(issensitiveclass("credential")).toBe(true);
+    expect(issensitiveclass("general")).toBe(false);
+    expect(issensitiveclass(undefined)).toBe(false);
+    expect(exportready([item]).ready).toBe(true);
+    expect(exportready([{ ...item, provenance: { ...provenance, stepid: " " } }]).ready).toBe(false);
+    expect(exportprovenancegate({ items: [item] }).allowed).toBe(true);
+    expect(exportprovenancegate({ items: [{ ...item, provenance: { ...provenance, stepid: " " } }] }).allowed).toBe(
+      false,
+    );
+  });
+});
+
+describe("expirememory", () => {
+  it("evaluates the user expiryrules, purges behind the confirmation and keeps the summaries for the audit trail", () => {
+    const rules: expiryrule[] = [
+      { pattern: "note:", lifetime: 60_000 },
+      { pattern: "*", lifetime: 600_000 },
+    ];
+    const fresh = itemof("note:1", "general", now);
+    const stale = itemof("note:2", "general", now - 120_000);
+    expect(matchingrule(rules, "note:1")?.pattern).toBe("note:");
+    expect(matchingrule(rules, "anything")?.pattern).toBe("*");
+    expect(matchingrule([], "note:1")).toBeUndefined();
+    expect(expiryof(fresh, rules)).toBe(now + 60_000);
+    expect(expiryof({ ...fresh, expiresat: now + 5 }, rules)).toBe(now + 5);
+    expect(expiryof(fresh, [])).toBeUndefined();
+    expect(expireditems([fresh, stale], rules, now).map((item) => item.key)).toEqual(["note:2"]);
+    const unconfirmed = purgeitems({ items: [fresh, stale], rules, confirmed: false, now });
+    expect(unconfirmed.purged).toHaveLength(0);
+    expect(unconfirmed.kept).toHaveLength(2);
+    const gate = expirygate({ confirmed: false, count: 1 });
+    expect(gate.allowed).toBe(false);
+    expect(gate.reason).toMatch(/waits behind the explicit confirmation/i);
+    expect(expirygate({ confirmed: true, count: 1 }).allowed).toBe(true);
+    expect(expirygate({ confirmed: true, count: 0 }).allowed).toBe(false);
+    const purged = purgeitems({ items: [fresh, stale], rules, confirmed: true, now });
+    expect(purged.kept.map((item) => item.key)).toEqual(["note:1"]);
+    expect(purged.purged.map((entry) => entry.key)).toEqual(["note:2"]);
+    expect(purged.purged[0]?.summary).toMatch(/purged/i);
+    expect(purged.purged[0]?.provenance.stepid).toBe("s1");
+    const outcome: purgeoutcome = purged.purged[0]!;
+    expect(outcome.at).toBe(now);
+  });
+});
+
+describe("quotawatch", () => {
+  it("ranks the cleanup candidates by age and expiry policy, proposes batches behind the per batch approval and reports the reclaimed bytes", () => {
+    const rules: expiryrule[] = [{ pattern: "note:", lifetime: 60_000 }];
+    const expired = itemof("note:expired", "general", now - 120_000);
+    const aged = itemof("cache:1", "capture", now - 500_000);
+    const young = itemof("cache:2", "capture", now - 1_000);
+    const plain = itemof("other:1", undefined, now);
+    const report = quotareportof({ usage: 500, quota: 1_000, items: [expired, aged, young, plain], rules, now });
+    expect(report.remaining).toBe(500);
+    expect(report.candidates?.map((candidate) => candidate.key)).toEqual(["note:expired", "cache:1", "cache:2"]);
+    expect(report.candidates?.[0]?.reason).toMatch(/expired under its user expiryrule/i);
+    expect(report.candidates?.[1]?.reason).toMatch(/aged past its capture/i);
+    expect(bytesreclaimed(report.candidates ?? []) > 0).toBe(true);
+    const batch = cleanupbatch(report.candidates ?? [], 2);
+    expect(batch).toHaveLength(2);
+    expect(cleanupbatch(report.candidates ?? [], undefined)).toHaveLength(3);
+    expect(quotacleanupgate({ approved: false, batch, touchesaudit: false }).allowed).toBe(false);
+    expect(quotacleanupgate({ approved: true, batch, touchesaudit: false }).allowed).toBe(true);
+    expect(quotacleanupgate({ approved: true, batch, touchesaudit: true }).allowed).toBe(false);
+    expect(quotacleanupgate({ approved: true, batch: [], touchesaudit: false }).allowed).toBe(false);
+    expect(bytesreclaimed(batch)).toBe(batch.reduce((total, candidate) => total + candidate.bytes, 0));
+  });
+});
+
+describe("encryptrest", () => {
+  it("derives the key from the user secret through the webcrypto api, roundtrips the value and migrates the predating items lazily", async () => {
+    const key = await derivekey("user secret", "salt:run1");
+    const value = { text: "sensitive body", count: 2 };
+    const envelope = await encryptvalue(key, value);
+    expect(envelope.iv).not.toBe("");
+    expect(envelope.payload).not.toContain("sensitive body");
+    const decrypted = await decryptvalue(key, envelope);
+    expect(decrypted).toEqual(value);
+    await expect(decryptvalue(await derivekey("other secret", "salt:run1"), envelope)).rejects.toThrow();
+    await expect(derivekey("", "salt")).rejects.toThrow(/secret/i);
+    const item = itemof("vault:1", "credential");
+    const migrated = await migrateitem({ item, key, enabled: true });
+    expect(migrated.encrypted).toBe(true);
+    expect(await migrateitem({ item: migrated, key, enabled: true })).toEqual(migrated);
+    expect(await migrateitem({ item, key, enabled: false })).toEqual(item);
+    expect(encryptmemorygate({ memoryclass: "credential", enabled: true, encrypted: false }).allowed).toBe(false);
+    expect(encryptmemorygate({ memoryclass: "credential", enabled: true, encrypted: true }).allowed).toBe(true);
+    expect(encryptmemorygate({ memoryclass: "credential", enabled: false, encrypted: false }).allowed).toBe(true);
+    expect(encryptmemorygate({ memoryclass: "general", enabled: true, encrypted: false }).allowed).toBe(true);
+    const secretgate = encryptionsecretgate({ secret: "user secret", consented: true });
+    expect(secretgate.allowed).toBe(true);
+    expect(encryptionsecretgate({ secret: "", consented: true }).allowed).toBe(false);
+    expect(encryptionsecretgate({ secret: "user secret", consented: false }).allowed).toBe(false);
+  });
+});
+
+describe("auditexport", () => {
+  it("bundles runs, memory, provenance and expiry rules into one record that streams without a size cap behind the explicit user action", () => {
+    const items = [itemof("note:1", "general"), itemof("vault:1", "credential")];
+    const rules: expiryrule[] = [{ pattern: "note:", lifetime: 60_000 }];
+    const record = auditexportof({
+      runs: [
+        { runid: "run1", planid: "plan", sessionid: "session", state: "completed", createdat: now, updatedat: now },
+      ],
+      items,
+      rules,
+      timeline: [{ at: now, runid: "run1", source: "step", summary: "completed" }],
+      locks: [{ holder: "run1", runid: "run1", sessionid: "session", acquiredat: now, expiresat: now + 1 }],
+      now,
+    });
+    expect(record.memory).toHaveLength(2);
+    expect(record.expiryrules).toEqual(rules);
+    const chunks = exportchunks(record, 200);
+    expect(chunks.length).toBeGreaterThan(1);
+    expect(chunks.at(-1)?.done).toBe(true);
+    expect(JSON.parse(chunks.map((chunk) => chunk.payload).join(""))).toEqual(record);
+    expect(() => exportchunks(record, 0)).toThrow(/chunk size/i);
+    expect(auditexportgate({ useraction: true }).allowed).toBe(true);
+    expect(auditexportgate({ useraction: false }).allowed).toBe(false);
+    const envelope = auditexportreport({ record });
+    expect(envelope.record.at).toBe(now);
+  });
+
+  it("persists the memory items, the expiry rules, the quotareport, the encryption flag and the purge summaries through the memory accessors", async () => {
+    const store = new sessionmemory(new fakeadapter());
+    await store.setmemoryitem(itemof("note:1", "general"));
+    await store.setmemoryitem(itemof("note:2", "general", now, now + 60_000));
+    expect((await store.getmemoryitems()).map((item) => item.key)).toEqual(["note:1", "note:2"]);
+    await store.setmemoryitem({ ...itemof("note:1", "general"), value: { text: "updated" } });
+    expect(await store.getmemoryitems()).toHaveLength(2);
+    await store.removememoryitems(["note:1"]);
+    expect((await store.getmemoryitems()).map((item) => item.key)).toEqual(["note:2"]);
+    await store.setexpiry([{ pattern: "note:", lifetime: 60_000 }]);
+    expect(await store.getexpiry()).toEqual([{ pattern: "note:", lifetime: 60_000 }]);
+    await store.setquotareport({ usage: 10, quota: 100, remaining: 90 });
+    expect((await store.getquotareport())?.remaining).toBe(90);
+    expect(await store.getencryptrest()).toBe(false);
+    await store.setencryptrest(true);
+    expect(await store.getencryptrest()).toBe(true);
+    await store.addpurgesummary({
+      key: "note:1",
+      summary: "purged",
+      provenance: provenanceof({ origin, runid: "run1", stepid: "s1", now }),
+      at: now,
+    });
+    expect((await store.listpurgesummaries()).map((entry) => entry.key)).toEqual(["note:1"]);
+    await store.setlastexpirepass(now);
+    expect(await store.getlastexpirepass()).toBe(now);
+    const exported = await store.getexport(now);
+    expect(exported.memory).toHaveLength(1);
+    expect(exported.expiryrules).toHaveLength(1);
+  });
+});

package/tests/migrateplan.test.ts

@@ -0,0 +1,349 @@
+import { describe, expect, it } from "vitest";
+import {
+  importautoma,
+  importselenium,
+  importtabular,
+  importuivision,
+  importv1plan,
+  migrateplanconversion,
+  parsecsvrows,
+  planlintfindings,
+} from "../cli.js";
+import { lintplanfile, parseplanfile } from "../plan.js";
+import { actionkindcatalog, portablerulesetof } from "../policy.js";
+import { clicommands, surfacepalette } from "../views.js";
+import { packageversion } from "../version.js";
+import { readFile } from "node:fs/promises";
+import type { planfile, planlintdiagnostic, portableruleset } from "../types.js";
+
+const now = 1_800_000_000_000;
+const ruleset: portableruleset = portablerulesetof(now);
+const capabilities = actionkindcatalog();
+
+/** Reads one importer fixture of the tests/code/importers source set the build copies into dist/fixtures/importers. */
+async function fixture(name: string): Promise<string> {
+  return readFile(`tests/code/importers/${name}`, "utf8");
+}
+
+/** Reads one json importer fixture as the parsed source object its importer reads. */
+async function jsonfixture(name: string): Promise<unknown> {
+  return JSON.parse(await fixture(name));
+}
+
+/** Lints one converted plan through the same lint engine the planlint command runs: the portable rule set, the cli findings and the full action kind capability set. */
+function lintconverted(file: planfile): planlintdiagnostic[] {
+  return [...lintplanfile({ file, ruleset, capabilities, now }), ...planlintfindings({ file, capabilities })];
+}
+
+/** The happy path fixtures of every importer with the format the migrateplan command declares for them. */
+const happy: Array<{ name: string; format: string }> = [
+  { name: "v1-plan.json", format: "v1" },
+  { name: "automa-workflow.json", format: "automa" },
+  { name: "selenium-side.json", format: "selenium" },
+  { name: "uivision-macro.json", format: "uivision" },
+  { name: "tabular-plan.csv", format: "tabular" },
+];
+
+/** The refusal fixtures of every importer: each one carries one entry the importer must refuse with the entry named. */
+const refusals: Array<{ name: string; format: string; pattern: RegExp }> = [
+  {
+    name: "v1-unknown.json",
+    format: "v1",
+    pattern: /version one step snap[\s\S]*screenshotpage outside the reviewed catalog/,
+  },
+  {
+    name: "automa-unknown.json",
+    format: "automa",
+    pattern: /automa block ping of type notification stays outside the conversion table/,
+  },
+  {
+    name: "selenium-unknown.json",
+    format: "selenium",
+    pattern: /selenium command roll of mouseOver stays outside the conversion table/,
+  },
+  {
+    name: "uivision-unknown.json",
+    format: "uivision",
+    pattern: /ui vision command xclick-2 of XClick stays outside the conversion table/,
+  },
+  {
+    name: "tabular-unknown.csv",
+    format: "tabular",
+    pattern: /tabular row 2[\s\S]*dragdrop outside the reviewed catalog/,
+  },
+];
+
+describe("migrateplan importer conversion", () => {
+  it("converts every happy fixture into a plan file that parses under schemastrict and lints with zero diagnostics", async () => {
+    for (const source of happy) {
+      const conversion = migrateplanconversion({ format: source.format, text: await fixture(source.name), now });
+      expect(conversion.file.version).toBe(packageversion);
+      expect(conversion.file.origin).toBe("https://example.org");
+      expect(conversion.file.steps.length).toBeGreaterThan(0);
+      const parsed = parseplanfile(JSON.parse(JSON.stringify(conversion.file)));
+      expect(parsed).toEqual(conversion.file);
+      expect(lintconverted(conversion.file)).toEqual([]);
+      expect(conversion.format).toBe(source.format);
+      expect(conversion.mapped).toBe(conversion.file.steps.length);
+      expect(conversion.notes[0]).toContain(`${source.format} importer converted the source`);
+      expect(conversion.notes[0]).toContain("the frozen plan file grammar carries no metadata field");
+    }
+  });
+
+  it("marks every converted sensitive step with the explicit gate declaration while the read steps carry none", async () => {
+    const v1 = importv1plan({ source: await jsonfixture("v1-plan.json"), now });
+    expect(v1.file.steps.map((step) => [step.id, step.kind, step.gate])).toEqual([
+      ["observe", "observe", undefined],
+      ["read", "readforms", undefined],
+      ["inspect", "inspect", undefined],
+      ["answer", "type", true],
+      ["pause", "delay", undefined],
+    ]);
+    expect(v1.file.grants).toEqual(["observe", "readforms", "inspect", "type", "delay"]);
+    const lifted = v1.file.steps.find((step) => step.id === "pause");
+    expect(lifted?.options).toBe('{"delay":3000}');
+    expect(v1.sourceversion).toBe("1");
+    expect(v1.notes.some((note) => note.includes("milliseconds field of 1 delay step lifted"))).toBe(true);
+  });
+
+  it("converts the automa blocks through the documented table and lands the trigger block in the report as the paused trigger", async () => {
+    const conversion = importautoma({ source: await jsonfixture("automa-workflow.json"), now });
+    expect(conversion.file.goal).toBe("contact survey sweep");
+    expect(conversion.file.steps.map((step) => [step.id, step.kind, step.target, step.value, step.gate])).toEqual([
+      ["tab", "tabcreate", undefined, "https://example.org/contact", true],
+      ["survey", "fillform", undefined, undefined, true],
+      ["send", "click", "button.primary", undefined, true],
+      ["hold", "delay", undefined, undefined, undefined],
+    ]);
+    const fields = JSON.parse(conversion.file.steps.find((step) => step.id === "survey")?.options ?? "{}") as {
+      fields: Array<Record<string, string>>;
+    };
+    expect(fields.fields).toEqual([
+      { name: "email", value: "survey@example.org", selector: "input[name=email]" },
+      { name: "message", value: "hello from the sweep", selector: "textarea" },
+    ]);
+    expect(JSON.parse(conversion.file.steps.find((step) => step.id === "hold")?.options ?? "{}")).toEqual({
+      delay: 1500,
+    });
+    expect(conversion.notes.some((note) => note.includes("paused trigger"))).toBe(true);
+    expect(conversion.sourceversion).toBe("1.0.0");
+  });
+
+  it("resolves the selenium locators, the open target and the pause milliseconds onto the reviewed grammar", async () => {
+    const conversion = importselenium({ source: await jsonfixture("selenium-side.json"), now });
+    expect(conversion.file.steps.map((step) => [step.id, step.kind, step.target, step.value, step.gate])).toEqual([
+      ["open", "navigate", undefined, "https://example.org/contact", true],
+      ["email", "type", "input[name=email]", "survey@example.org", true],
+      ["keys", "appendtext", "input[name=email]", " hello", true],
+      ["pick", "select", "#topic", "general", true],
+      ["send", "click", "button.primary", undefined, true],
+      ["hold", "delay", undefined, undefined, undefined],
+    ]);
+    expect(JSON.parse(conversion.file.steps.find((step) => step.id === "hold")?.options ?? "{}")).toEqual({
+      delay: 2000,
+    });
+    expect(conversion.sourceversion).toBe("2.0");
+  });
+
+  it("converts the ui vision macro with its derived stable step ids and the waittext verification", async () => {
+    const conversion = importuivision({ source: await jsonfixture("uivision-macro.json"), now });
+    expect(conversion.file.goal).toBe("example releases read");
+    expect(conversion.file.steps.map((step) => [step.id, step.kind, step.target, step.value, step.gate])).toEqual([
+      ["open-1", "navigate", undefined, "https://example.org/releases", true],
+      ["click-2", "click", "nav a.releases", undefined, true],
+      ["type-3", "type", "input[name=filter]", "release notes", true],
+      ["verifytext-4", "waittext", "main h1", "Releases", undefined],
+    ]);
+  });
+
+  it("converts the tabular rows onto the step grammar with the preface metadata and the quoted csv cells", async () => {
+    const conversion = importtabular({ text: await fixture("tabular-plan.csv"), now });
+    expect(conversion.file.goal).toBe("Survey the releases page of the example project");
+    expect(conversion.file.steps.map((step) => [step.id, step.kind, step.target, step.value, step.gate])).toEqual([
+      ["observe-1", "observe", undefined, undefined, undefined],
+      ["readtext-2", "readtext", "main", undefined, undefined],
+      ["countelements-3", "countelements", "main section", undefined, undefined],
+      ["type-4", "type", "input[name=filter]", "release notes, digest", true],
+    ]);
+  });
+
+  it("reads the tabular preface markers through the linear scan that closed the polynomial regular expression alerts", async () => {
+    /* the marker body accepts any spacing after the hash and the colon, and a marker line with no value never clears a value an earlier line set */
+    const tight = importtabular({
+      text: "#goal:tight\n#origin:https://example.org\nstep,target,value\nobserve,,\n",
+      now,
+    });
+    expect(tight.file.goal).toBe("tight");
+    expect(tight.file.origin).toBe("https://example.org");
+    const spaced = importtabular({
+      text: "#   goal:   spaced survey\n# origin:   https://example.org\nstep,target,value\nobserve,,\n",
+      now,
+    });
+    expect(spaced.file.goal).toBe("spaced survey");
+    expect(spaced.file.origin).toBe("https://example.org");
+    const kept = importtabular({
+      text: "# goal: kept\n# goal:\n# origin: https://example.org\nstep,target,value\nobserve,,\n",
+      now,
+    });
+    expect(kept.file.goal).toBe("kept");
+    const sameorigin = importtabular({
+      text: "# goal: g\n# origin: https://example.org\n# origin:\nstep,target,value\nobserve,,\n",
+      now,
+    });
+    expect(sameorigin.file.origin).toBe("https://example.org");
+  });
+});
+
+describe("migrateplan refusal semantics", () => {
+  it("refuses every unmappable entry with the source entry named, never with a silent drop", async () => {
+    for (const source of refusals) {
+      const text = await fixture(source.name);
+      expect(() => migrateplanconversion({ format: source.format, text, now })).toThrow(source.pattern);
+    }
+  });
+
+  it("refuses the formats, the shapes and the locators it cannot map instead of guessing", async () => {
+    expect(() => migrateplanconversion({ format: "playwright", text: "{}", now })).toThrow(
+      /stays outside the v1, automa, selenium, uivision and tabular source formats/,
+    );
+    expect(() => migrateplanconversion({ format: "v1", text: "not json", now })).toThrow(/v1 source parses no json/);
+    expect(() =>
+      importv1plan({
+        source: {
+          version: "1",
+          goal: "g",
+          origin: "https://example.org",
+          steps: [{ id: "s", action: "observe", label: "l", legacy: true }],
+        },
+        now,
+      }),
+    ).toThrow(/unknown field legacy/);
+    expect(() =>
+      importv1plan({
+        source: {
+          version: "1",
+          goal: "g",
+          origin: "http://example.org",
+          steps: [{ id: "s", action: "observe", label: "l" }],
+        },
+        now,
+      }),
+    ).toThrow(/HTTPS/);
+    expect(() =>
+      importv1plan({
+        source: {
+          version: "1",
+          goal: "g",
+          origin: "https://example.org",
+          steps: [{ id: "s", action: "click", label: "l", milliseconds: 5 }],
+        },
+        now,
+      }),
+    ).toThrow(/only the delay action lifts/);
+    expect(() =>
+      importautoma({
+        source: {
+          name: "n",
+          blocks: {
+            tab: { type: "newtab", data: { url: "https://example.org" } },
+            away: { type: "newtab", data: { url: "https://other.example" } },
+          },
+        },
+        now,
+      }),
+    ).toThrow(/automa block away of type newtab navigates to https:\/\/other\.example/);
+    expect(() =>
+      importautoma({
+        source: { name: "n", blocks: { only: { type: "click-element", data: { selector: "button" } } } },
+        now,
+      }),
+    ).toThrow(/carries no newtab block/);
+    expect(() =>
+      importselenium({ source: { version: "2.0", name: "n", url: "https://example.org", tests: [] }, now }),
+    ).toThrow(/carries 0 tests; one plan addresses exactly one test/);
+    expect(() =>
+      importselenium({
+        source: {
+          version: "2.0",
+          name: "n",
+          url: "https://example.org",
+          tests: [{ name: "t", commands: [{ id: "x", command: "click", target: "xpath=//button", value: "" }] }],
+        },
+        now,
+      }),
+    ).toThrow(/outside the css=, id= and name= locator prefixes/);
+    expect(() =>
+      importuivision({ source: { Name: "n", Commands: [{ Command: "click", Target: "css=button", Value: "" }] }, now }),
+    ).toThrow(/carries no open command/);
+    expect(() => importtabular({ text: "step,target,value\nobserve,,\n", now })).toThrow(/no `# goal:` preface line/);
+    expect(() => importtabular({ text: "# goal: g\nstep,target,value\nobserve,,\n", now })).toThrow(
+      /no `# origin:` preface line/,
+    );
+    expect(() =>
+      importtabular({ text: "# goal: g\n# origin: http://example.org\nstep,target,value\nobserve,,\n", now }),
+    ).toThrow(/HTTPS origin/);
+    expect(() =>
+      importtabular({ text: "# goal: g\n# origin: https://example.org\nstep,target,extra\nobserve,,\n", now }),
+    ).toThrow(/column extra outside the step, target and value columns/);
+  });
+});
+
+describe("the csv parser of the tabular importer", () => {
+  it("parses headers, quoted cells, escaped quotes, embedded newlines and crlf line endings while refusing an unterminated quote", () => {
+    expect(parsecsvrows("step,target,value\nobserve,,\n")).toEqual([
+      ["step", "target", "value"],
+      ["observe", "", ""],
+    ]);
+    expect(parsecsvrows('a,b\n1,"x,y"\n')).toEqual([
+      ["a", "b"],
+      ["1", "x,y"],
+    ]);
+    expect(parsecsvrows('a,b\n1,"say ""hi"""\n')).toEqual([
+      ["a", "b"],
+      ["1", 'say "hi"'],
+    ]);
+    expect(parsecsvrows('a,b,c\n1,"two\nlines",3')).toEqual([
+      ["a", "b", "c"],
+      ["1", "two\nlines", "3"],
+    ]);
+    expect(parsecsvrows("a,b\r\n1,2\r\n")).toEqual([
+      ["a", "b"],
+      ["1", "2"],
+    ]);
+    expect(parsecsvrows('a,b\n,"","x"\n')).toEqual([
+      ["a", "b"],
+      ["", "", "x"],
+    ]);
+    expect(parsecsvrows('a,b\n,"""",x\n')).toEqual([
+      ["a", "b"],
+      ["", '"', "x"],
+    ]);
+    expect(parsecsvrows("")).toEqual([]);
+    expect(() => parsecsvrows('a,"unterminated')).toThrow(/ends inside a quoted cell/);
+  });
+});
+
+describe("the migrateplan command surface", () => {
+  it("registers the migrateplan command in the shared registry the cli help prints", () => {
+    const entry = clicommands(surfacepalette()).find((command) => command.id === "migrateplan");
+    expect(entry?.terminal).toBe(true);
+    expect(entry?.label).toContain("foreign plan source");
+    expect(entry?.keywords).toContain("automa");
+  });
+
+  it("keeps the conversion idempotent: converting the already converted output yields the same plan", async () => {
+    const first = migrateplanconversion({ format: "v1", text: await fixture("v1-plan.json"), now });
+    const serialized = JSON.stringify(first.file, null, 2);
+    const second = migrateplanconversion({ format: "v1", text: serialized, now: now + 5_000 });
+    expect(second.file).toEqual(first.file);
+    expect(second.mapped).toBe(first.mapped);
+    expect(second.notes.some((note) => note.includes("passes it through unchanged"))).toBe(true);
+    const tabular = migrateplanconversion({ format: "tabular", text: await fixture("tabular-plan.csv"), now });
+    const reimported = migrateplanconversion({
+      format: "tabular",
+      text: await fixture("tabular-plan.csv"),
+      now: now + 5_000,
+    });
+    expect(reimported.file).toEqual(tabular.file);
+  });
+});