@milaboratories/pl-middle-layer 1.68.2 → 1.69.0

package/src/model/sharing_model.test.ts

@@ -1,6 +1,13 @@
 import { test, expect } from "vitest";
 import { Role } from "@milaboratories/pl-client";
-import { canGrantToEveryone, canImpersonate } from "./sharing_model";
+import {
+  canGrantToEveryone,
+  canImpersonate,
+  decodeEnvelopeData,
+  EnvelopeSchemaVersionCurrent,
+  envelopeProjectMap,
+  normalizeEnvelopeData,
+} from "./sharing_model";
 
 // canImpersonate is the admin gate for "open another user's root". It must be strictly
 // stricter than canGrantToEveryone: a regular USER may share their own projects but must
@@ -20,3 +27,110 @@ test("canGrantToEveryone and canImpersonate does not include USER", () => {
   expect(canGrantToEveryone(Role.USER)).toBe(false);
   expect(canImpersonate(Role.USER)).toBe(false);
 });
+
+//
+// Envelope decode — the recognise-or-hide gate every reader of a share passes through.
+//
+// Pure by construction: the gate is a function of the blob, and the three sites that
+// discover envelopes (the pending view, the live-envelope view the accept flow reads,
+// and the donor's own outbox) all skip an envelope this returns `undefined` for. So an
+// envelope that does not decode cannot be offered, accepted, or listed.
+
+/** A v1 envelope, exactly as one written before the payload discriminant existed: the
+ *  project map sits at the top level and there is no `payload` field. */
+const v1Envelope = {
+  schemaVersion: 1,
+  shareId: "5d1a6f6c-2b6e-4a3f-9c2d-8f0e1b7a4c55",
+  sharedAt: 1_700_000_000_000,
+  expiresAt: null,
+  mode: "copy",
+  sender: "donor",
+  title: "Two projects",
+  projects: {
+    "9c7e4d10-2b83-4f6a-91d5-7e0c3a8b5f42": {
+      label: "Project 1",
+      source: "42",
+      updatedAt: 1_700_000_000_000,
+    },
+  },
+};
+
+const blob = (envelope: unknown) => Buffer.from(JSON.stringify(envelope), "utf-8");
+
+test("a v1 envelope still decodes, and reads as a share of projects", () => {
+  const data = decodeEnvelopeData(blob(v1Envelope));
+
+  // Upcast on read: past the decode nothing knows two shapes ever existed.
+  expect(data?.schemaVersion).toBe(EnvelopeSchemaVersionCurrent);
+  expect(data?.payload).toStrictEqual({ kind: "projects", projects: v1Envelope.projects });
+  expect(envelopeProjectMap(data!)).toStrictEqual(v1Envelope.projects);
+
+  // Everything a view renders survives the upcast unchanged.
+  expect(data).toMatchObject({
+    shareId: v1Envelope.shareId,
+    sharedAt: v1Envelope.sharedAt,
+    expiresAt: null,
+    mode: "copy",
+    sender: "donor",
+    title: "Two projects",
+  });
+});
+
+test("a current envelope carrying a template decodes as one", () => {
+  const data = decodeEnvelopeData(
+    blob({
+      ...v1Envelope,
+      schemaVersion: EnvelopeSchemaVersionCurrent,
+      projects: undefined,
+      payload: {
+        kind: "template",
+        document: { schema: "template-v1", blocks: [] },
+        label: "A pipeline",
+        from: "donor",
+      },
+    }),
+  );
+
+  expect(data?.payload).toStrictEqual({
+    kind: "template",
+    document: { schema: "template-v1", blocks: [] },
+    label: "A pipeline",
+    from: "donor",
+  });
+  // A template payload carries no project snapshot, so a project-shaped reader sees nothing
+  // rather than something it would then try to copy.
+  expect(envelopeProjectMap(data!)).toStrictEqual({});
+});
+
+test("an envelope whose payload kind this build does not know does not decode at all", () => {
+  // The whole point of the discriminant: a share this build cannot act on is hidden rather
+  // than offered, and the decode is where that is decided — once, for every reader.
+  expect(
+    decodeEnvelopeData(
+      blob({
+        ...v1Envelope,
+        schemaVersion: EnvelopeSchemaVersionCurrent,
+        projects: undefined,
+        payload: { kind: "workspace", whatever: true },
+      }),
+    ),
+  ).toBeUndefined();
+});
+
+test("an envelope from a newer schema does not decode either", () => {
+  expect(
+    decodeEnvelopeData(blob({ ...v1Envelope, schemaVersion: EnvelopeSchemaVersionCurrent + 1 })),
+  ).toBeUndefined();
+});
+
+test("a v1 envelope with no project map at all does not decode", () => {
+  // There is no payload to reconstruct: a v1 blob without `projects` describes nothing,
+  // which is not the same as describing an empty pack.
+  expect(decodeEnvelopeData(blob({ ...v1Envelope, projects: undefined }))).toBeUndefined();
+});
+
+test("anything that is not an envelope object does not decode", () => {
+  expect(normalizeEnvelopeData(null)).toBeUndefined();
+  expect(normalizeEnvelopeData("an envelope")).toBeUndefined();
+  expect(normalizeEnvelopeData(42)).toBeUndefined();
+});

package/src/model/sharing_model.ts

@@ -1,6 +1,6 @@
 import type { ResourceType, Role } from "@milaboratories/pl-client";
 import { Role as RoleEnum } from "@milaboratories/pl-client";
-import type { Branded, ProjectId } from "@milaboratories/pl-model-common";
+import type { Branded, ProjectId, ProjectTemplateV1 } from "@milaboratories/pl-model-common";
 import { randomUUID } from "node:crypto";
 
 /**
@@ -84,23 +84,65 @@ export function canImpersonate(role: Role | null): boolean {
   }
 }
 
-/** One project's snapshot inside an envelope, keyed by {@link ProjectFieldUuid} in {@link EnvelopeData.projects}. */
+/** One project's snapshot inside an envelope, keyed by {@link ProjectFieldUuid} in a
+ *  `projects` {@link EnvelopePayload}. */
 export interface EnvelopeProject {
   label: string; // carried so the pending-share UI renders without traversing into the project
   source: ProjectId; // donor's source projectId; supersedes a prior share and matches the snapshot to its live source on change
   updatedAt: number; // ms epoch of the last (re)snapshot
 }
 
-/** Immutable `data` on a SharedEnvelope, set at createEphemeral, never mutated. */
+/**
+ * What a share carries. The discriminant is what a reader checks before anything else: a
+ * client that does not know a kind hides the share instead of offering something it cannot
+ * act on.
+ *
+ * `projects` snapshots ride as `project/{uuid}` fields on the envelope and this map only
+ * describes them; a `template` payload has no fields at all — the document is right here.
+ */
+export type EnvelopePayload =
+  | { kind: "projects"; projects: Record<ProjectFieldUuid, EnvelopeProject> }
+  | {
+      kind: "template";
+      document: ProjectTemplateV1;
+      /** Label to give the template on the recipient's own shelf. */
+      label: string;
+      /** Donor login, kept on the accepted template as its provenance. */
+      from: string;
+    };
+
+export type EnvelopePayloadKind = EnvelopePayload["kind"];
+
+/** Every envelope schema version this build can read. Adding a version here is what makes
+ *  {@link normalizeEnvelopeData} accept it; bumping {@link EnvelopeSchemaVersionCurrent} to a
+ *  version missing from this union is a compile error. */
+export type EnvelopeSchemaVersion = 1 | 2;
+
+/** Version written into every new envelope. Bumped from 1 when the payload became discriminated. */
+export const EnvelopeSchemaVersionCurrent = 2 satisfies EnvelopeSchemaVersion;
+
+/**
+ * Immutable `data` on a SharedEnvelope, set at createEphemeral, never mutated.
+ *
+ * Always the current version in memory: a v1 envelope (project map at the top level, no
+ * `payload` field) is upcast on read by {@link normalizeEnvelopeData}, so no reader past the
+ * decode has to know that two shapes ever existed.
+ */
 export interface EnvelopeData {
-  schemaVersion: 1;
+  schemaVersion: typeof EnvelopeSchemaVersionCurrent;
   shareId: ShareId; // donor-generated UUID; logical share identity, stable across changes
   sharedAt: number; // ms epoch; this instance's creation time — distinguishes instances of one shareId
   expiresAt: number | null; // ms epoch; sharedAt + ttl (default 14 days) for a targeted share; null for share-with-everybody (never expires)
   mode: EnvelopeMode; // what the acceptor's app should do with the contents
   sender: string; // donor login (informational; backend granted_by is authoritative)
   title: string; // display name shown to recipients; defaults to the first project's name
-  projects: Record<ProjectFieldUuid, EnvelopeProject>; // contained projects, keyed by project field uuid
+  payload: EnvelopePayload; // what the share carries
+}
+
+/** The project map of a projects-payload envelope, or `{}` for any other payload — the one
+ *  place a project-shaped reader turns a payload into the map it expects. */
+export function envelopeProjectMap(data: EnvelopeData): Record<ProjectFieldUuid, EnvelopeProject> {
+  return data.payload.kind === "projects" ? data.payload.projects : {};
 }
 
 /** Dynamic field on SharingState, one per handled share, keyed by shareId. */
@@ -110,7 +152,7 @@ export interface SharingDecision {
   decision: "accepted" | "rejected";
   timestamp: number; // ms epoch — when the acceptor acted
   envelopeSharedAt: number; // the acted-on envelope instance's sharedAt — pins which instance was handled (paired with the shareId key; the resource id is never stored)
-  acceptedProjects: string[]; // ids of the projects created in the acceptor's list ([] for a rejected share)
+  acceptedProjects: string[]; // ids of the projects created in the acceptor's list ([] for a rejected share, and for a template share, which creates none)
 }
 
 /** Dynamic field on SharedEnvelope, one per recipient who accepted or rejected, keyed
@@ -134,10 +176,45 @@ export interface EnvelopeAcceptance {
  * Single owner of the raw-data → {@link EnvelopeData} decode. The envelope's immutable `data`
  * blob is UTF-8 JSON set once at createEphemeral; every site that reads it from a raw resource
  * `data` byte buffer (the basic-resource read path) goes through here. The reactive tree-node
- * path uses `node.getDataAsJson<EnvelopeData>()`, which decodes the same JSON.
+ * path decodes the same JSON with `getDataAsJson` and normalizes it with
+ * {@link normalizeEnvelopeData} — both paths must, so neither sees the raw v1 shape.
+ *
+ * `undefined` for an envelope this build cannot act on; see {@link normalizeEnvelopeData}.
  */
-export function decodeEnvelopeData(data: Uint8Array): EnvelopeData {
-  return JSON.parse(Buffer.from(data).toString("utf-8")) as EnvelopeData;
+export function decodeEnvelopeData(data: Uint8Array): EnvelopeData | undefined {
+  return normalizeEnvelopeData(JSON.parse(Buffer.from(data).toString("utf-8")));
+}
+
+/**
+ * Brings a decoded envelope blob to the current shape, or reports that this build cannot act
+ * on it by returning `undefined` — an unknown `schemaVersion` or an unknown payload kind. A
+ * caller hides such a share rather than offering the recipient something it cannot handle.
+ *
+ * A v1 envelope carried its project map at the top level and had no `payload` field; it reads
+ * here as a `projects` payload, so envelopes written before the discriminant existed keep
+ * working unchanged.
+ */
+export function normalizeEnvelopeData(raw: unknown): EnvelopeData | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined;
+  const e = raw as RawEnvelopeData;
+  if (!Object.hasOwn(ReadableSchemaVersions, e.schemaVersion)) return undefined;
+
+  const payload =
+    e.payload ??
+    (e.projects !== undefined ? ({ kind: "projects", projects: e.projects } as const) : undefined);
+  if (payload === undefined) return undefined;
+  if (!Object.hasOwn(KnownPayloadKinds, payload.kind)) return undefined;
+
+  return {
+    schemaVersion: EnvelopeSchemaVersionCurrent,
+    shareId: e.shareId,
+    sharedAt: e.sharedAt,
+    expiresAt: e.expiresAt,
+    mode: e.mode,
+    sender: e.sender,
+    title: e.title,
+    payload,
+  };
 }
 
 /**
@@ -166,3 +243,51 @@ export type ShareProjectsOptions =
       title: string;
       mode: EnvelopeMode;
     };
+
+/**
+ * Options for {@link MiddleLayer.shareTemplate}.
+ *
+ * Recipients XOR everyone, exactly as {@link ShareProjectsOptions}, minus the mode: a template
+ * share is always granted read-only, because the recipient copies no resource out of the
+ * envelope — the document is in the envelope's own data.
+ */
+export type ShareTemplateOptions =
+  | {
+      recipients: string[]; // recipient logins
+      title: string; // display name shown to recipients; defaults to the template's label
+    }
+  | {
+      everyone: true; // share with all users on the server
+      title: string;
+    };
+
+//
+// Internals
+//
+
+/** Every payload kind this build can act on; anything else is hidden rather than offered.
+ *  Keyed by {@link EnvelopePayloadKind}, so adding a kind to {@link EnvelopePayload} without
+ *  teaching the decoder about it is a compile error, not a share that silently disappears. */
+const KnownPayloadKinds: Record<EnvelopePayloadKind, true> = {
+  projects: true,
+  template: true,
+};
+
+/** Every schema version {@link normalizeEnvelopeData} accepts. Keyed by
+ *  {@link EnvelopeSchemaVersion}, so widening that union without deciding how the new shape
+ *  is upcast is a compile error. */
+const ReadableSchemaVersions: Record<EnvelopeSchemaVersion, true> = {
+  1: true,
+  2: true,
+};
+
+/**
+ * The envelope blob as it comes off the wire, before {@link normalizeEnvelopeData} decides
+ * whether this build can act on it: the version is any number, the payload may be missing,
+ * and `projects` is the v1 top-level project map.
+ */
+type RawEnvelopeData = Omit<EnvelopeData, "schemaVersion" | "payload"> & {
+  schemaVersion: number;
+  payload?: EnvelopePayload;
+  projects?: Record<ProjectFieldUuid, EnvelopeProject>;
+};

package/src/model/template_share.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "vitest";
+import type {
+  BlockKindSelectorReference,
+  BlockPackLocationReference,
+  ProjectTemplateV1,
+  ProjectTemplateV1Entry,
+} from "@milaboratories/pl-model-common";
+import { PROJECT_TEMPLATE_SCHEMA_V1 } from "@milaboratories/pl-model-common";
+import { unshareableTemplateEntries } from "./template_share";
+
+/**
+ * Whether a stored template may travel to another machine.
+ *
+ * A function of the document alone, which is why it is asked both when a share is attempted
+ * and when a template is merely displayed — the refusal has to be visible on the template
+ * itself, not only after the user tries.
+ */
+
+const KIND = "@platforma-open/milaboratories.demo.kind@^1.0.0" as BlockKindSelectorReference;
+
+const entry = (id: string, location?: string): ProjectTemplateV1Entry => ({
+  id,
+  kind: KIND,
+  params: {},
+  ...(location !== undefined ? { location: location as BlockPackLocationReference } : {}),
+});
+
+const documentOf = (...blocks: ProjectTemplateV1Entry[]): ProjectTemplateV1 => ({
+  schema: PROJECT_TEMPLATE_SCHEMA_V1,
+  blocks,
+});
+
+describe("unshareableTemplateEntries", () => {
+  test("a template whose entries name no place at all can be shared", () => {
+    // The common case: every entry resolves through its kind, which means the same thing
+    // on the recipient's machine as it does here.
+    expect(unshareableTemplateEntries(documentOf(entry("a"), entry("b")))).toStrictEqual([]);
+  });
+
+  test("an entry installed from a folder on this machine refuses the share, and says which folder", () => {
+    const problems = unshareableTemplateEntries(
+      documentOf(entry("a"), entry("b", "file:///Users/dev/blocks/demo/block")),
+    );
+
+    expect(problems.map((p) => p.entryId)).toStrictEqual(["b"]);
+    expect(problems[0].error).toContain("file:///Users/dev/blocks/demo/block");
+  });
+
+  test("every offending entry is reported, not only the first", () => {
+    // A UI names each block once instead of sending its user round the loop per entry.
+    const problems = unshareableTemplateEntries(
+      documentOf(
+        entry("a", "file:///blocks/a"),
+        entry("b"),
+        entry("c", "FILE:///blocks/c"), // the scheme is case-insensitive
+      ),
+    );
+
+    expect(problems.map((p) => p.entryId)).toStrictEqual(["a", "c"]);
+  });
+
+  test("a location whose scheme cannot be read is refused too", () => {
+    // Nothing can resolve it anywhere, here included — so the reason differs from the
+    // `file:` one, and the message says so rather than blaming the recipient's machine.
+    const problems = unshareableTemplateEntries(documentOf(entry("a", "/blocks/a")));
+
+    expect(problems.map((p) => p.entryId)).toStrictEqual(["a"]);
+    expect(problems[0].error).toContain("nothing can resolve");
+  });
+
+  test("a location naming a place both machines can reach is not refused", () => {
+    // The rule is about a place that means something different elsewhere, not about
+    // locations as such.
+    expect(
+      unshareableTemplateEntries(documentOf(entry("a", "https://blocks.example.org/demo"))),
+    ).toStrictEqual([]);
+  });
+});

package/src/model/template_share.ts

@@ -0,0 +1,52 @@
+import type { ProjectTemplateV1 } from "@milaboratories/pl-model-common";
+import { parseBlockPackLocation } from "@milaboratories/pl-model-common";
+
+/** One template entry standing in the way of sharing the template, and why. */
+export type TemplateShareProblem = {
+  /** The template-local id of the entry the problem belongs to; on an exported template it is
+   *  the block's project-local uuid. */
+  readonly entryId: string;
+  readonly error: string;
+};
+
+/**
+ * Every entry of a template that cannot travel to another machine, or an empty list for a
+ * template that can be shared.
+ *
+ * An entry's `location` names a place rather than a name, and a `file:` place is a folder on
+ * the author's own disk: a recipient resolving it finds nothing, or worse finds something
+ * else. Such a template stays perfectly usable where it was made, so it is stored and applied
+ * as normal — only sharing it is refused.
+ *
+ * A location whose scheme cannot be read is refused for the same reason: nothing can resolve
+ * it anywhere, here included.
+ *
+ * Every offending entry is reported, not only the first, so a UI can name each block instead
+ * of sending its user round the loop once per entry.
+ */
+export function unshareableTemplateEntries(
+  document: ProjectTemplateV1,
+): readonly TemplateShareProblem[] {
+  const problems: TemplateShareProblem[] = [];
+  for (const entry of document.blocks) {
+    if (entry.location === undefined) continue;
+    let scheme: string;
+    try {
+      scheme = parseBlockPackLocation(entry.location).scheme;
+    } catch (e) {
+      problems.push({
+        entryId: entry.id,
+        error: `Block is installed from a location nothing can resolve: ${e instanceof Error ? e.message : String(e)}`,
+      });
+      continue;
+    }
+    if (scheme === "file")
+      problems.push({
+        entryId: entry.id,
+        error:
+          `Block is installed from ${entry.location}, a folder on this machine — it resolves ` +
+          "to nothing on the recipient's, so this template cannot be shared",
+      });
+  }
+  return problems;
+}

package/src/mutator/sharing.ts

@@ -2,7 +2,7 @@ import type { PlTransaction, ResourceRef, SignedResourceId } from "@milaboratori
 import { field, isNotNullSignedResourceId, resourceIdToString } from "@milaboratories/pl-client";
 import { randomUUID } from "node:crypto";
 import type { ProjectMeta } from "@milaboratories/pl-model-middle-layer";
-import type { ProjectId } from "@milaboratories/pl-model-common";
+import type { ProjectId, ProjectTemplateV1 } from "@milaboratories/pl-model-common";
 import { ProjectMetaKey } from "../model/project_model";
 import { duplicateProject } from "./project";
 import type {
@@ -15,6 +15,7 @@ import type {
   SharingDecision,
 } from "../model/sharing_model";
 import {
+  EnvelopeSchemaVersionCurrent,
   SharedEnvelopeResourceType,
   acceptanceField,
   decisionField,
@@ -101,14 +102,14 @@ export async function buildShareEnvelope(
   }
 
   const data: EnvelopeData = {
-    schemaVersion: 1,
+    schemaVersion: EnvelopeSchemaVersionCurrent,
     shareId,
     sharedAt,
     expiresAt: params.expiresAt,
     mode: params.mode,
     sender: params.sender,
     title: params.title,
-    projects,
+    payload: { kind: "projects", projects },
   };
 
   // Immutable data set once at creation, never altered.
@@ -127,6 +128,57 @@ export async function buildShareEnvelope(
   return { envelope, data };
 }
 
+/**
+ * Builds one {@link SharedEnvelopeResourceType} carrying a template document on the donor side,
+ * and attaches it under `{shareId}` on the donor's outbox. The caller issues the grant — always
+ * read-only — and commits, keeping create + grant atomic.
+ *
+ * There is nothing to snapshot and no input field to seal: the document is the whole payload and
+ * rides in the envelope's immutable `data`, which is also why the recipient needs no write access
+ * (it copies no resource out of the envelope).
+ *
+ * @returns the new envelope resource and the generated `EnvelopeData`.
+ */
+export function buildTemplateShareEnvelope(
+  tx: PlTransaction,
+  outboxRid: SignedResourceId,
+  template: { document: ProjectTemplateV1; label: string },
+  params: {
+    sender: string;
+    title: string;
+    /** ms epoch; sharedAt + ttl for a targeted share, null for share-with-everybody. */
+    expiresAt: number | null;
+    /** Existing shareId for a change; a fresh one is minted when omitted. */
+    shareId?: ShareId;
+    sharedAt?: number;
+  },
+): { envelope: ResourceRef; data: EnvelopeData } {
+  const data: EnvelopeData = {
+    schemaVersion: EnvelopeSchemaVersionCurrent,
+    shareId: params.shareId ?? newShareId(),
+    sharedAt: params.sharedAt ?? Date.now(),
+    expiresAt: params.expiresAt,
+    mode: "read-only",
+    sender: params.sender,
+    title: params.title,
+    payload: {
+      kind: "template",
+      document: template.document,
+      label: template.label,
+      from: params.sender,
+    },
+  };
+
+  // Immutable data set once at creation, never altered.
+  const envelope = tx.createEphemeral(SharedEnvelopeResourceType, JSON.stringify(data));
+
+  // Attach to the outbox under {shareId} in the same transaction so the held-resource rule
+  // keeps the ephemeral envelope alive.
+  tx.createField(field(outboxRid, data.shareId), "Dynamic", envelope);
+
+  return { envelope, data };
+}
+
 /**
  * Records a response onto the envelope as a dynamic `acceptance/{login}` field: the acceptor
  * writing their own decision (their writable grant permits it), or the donor transferring an

package/src/mutator/template.ts

@@ -0,0 +1,75 @@
+import type { PlTransaction, ResourceRef, SignedResourceId } from "@milaboratories/pl-client";
+import { field, isNullSignedResourceId, resourceIdToString } from "@milaboratories/pl-client";
+import { randomUUID } from "node:crypto";
+import type { StoredTemplateData, TemplateId } from "../middle_layer/template_list";
+import {
+  TemplateCreatedTimestamp,
+  TemplateLabelKey,
+  TemplateResourceType,
+} from "../middle_layer/template_list";
+
+/**
+ * Creates one `UserTemplate` inside the given write transaction and attaches it to the
+ * templates list under a freshly minted uuid field.
+ *
+ * Create and attach are the same transaction on purpose: an ephemeral resource nothing
+ * holds is collectable, so the list field is what keeps the template alive.
+ *
+ * The document rides in the immutable `data` blob, set once here and never altered; only
+ * the label and the creation timestamp go to KV, and only the label is ever written again.
+ *
+ * @returns the new template resource; the caller reads its `globalId` after the commit.
+ */
+export function createTemplate(
+  tx: PlTransaction,
+  listRid: SignedResourceId,
+  label: string,
+  data: StoredTemplateData,
+): ResourceRef {
+  const tpl = tx.createEphemeral(TemplateResourceType, JSON.stringify(data));
+  tx.lock(tpl);
+  tx.setKValue(tpl, TemplateLabelKey, JSON.stringify(label));
+  tx.setKValue(tpl, TemplateCreatedTimestamp, String(Date.now()));
+  tx.createField(field(listRid, randomUUID()), "Dynamic", tpl);
+  return tpl;
+}
+
+/** Renames a stored template. Touches the label KV entry and nothing else, so the stored
+ *  document stays byte-identical. */
+export function renameTemplate(tx: PlTransaction, rid: SignedResourceId, label: string): void {
+  tx.setKValue(rid, TemplateLabelKey, JSON.stringify(label));
+}
+
+/**
+ * Detaches a template from the templates list, which is what destroys it — the list field is
+ * the only thing holding the ephemeral resource.
+ *
+ * The field name is a uuid unrelated to the template id, so the field carrying the template
+ * is found by value, the same way a project is removed from the project list.
+ */
+export async function deleteTemplate(
+  tx: PlTransaction,
+  listRid: SignedResourceId,
+  id: TemplateId,
+): Promise<void> {
+  const fieldName = await findTemplateField(tx, listRid, id);
+  if (fieldName === undefined) throw new Error(`Template ${id} not found in template list.`);
+  tx.removeField(field(listRid, fieldName));
+}
+
+//
+// Internals
+//
+
+async function findTemplateField(
+  tx: PlTransaction,
+  listRid: SignedResourceId,
+  id: TemplateId,
+): Promise<string | undefined> {
+  const data = await tx.getResourceData(listRid, true);
+  for (const f of data.fields) {
+    if (isNullSignedResourceId(f.value)) continue;
+    if (resourceIdToString(f.value) === (id as string)) return f.name;
+  }
+  return undefined;
+}

package/src/test/with_ml.ts

@@ -0,0 +1,38 @@
+import path from "path";
+import { randomUUID } from "node:crypto";
+import type { PlClient } from "@milaboratories/pl-client";
+import { TestHelpers } from "@milaboratories/pl-client";
+import { MiddleLayer } from "../middle_layer/middle_layer";
+
+/**
+ * A live {@link MiddleLayer} over a temporary root, closed again when the body returns.
+ *
+ * Needs a backend: the client comes from `PL_ADDRESS` (plus `PL_TEST_USER` /
+ * `PL_TEST_PASSWORD` where the server requires auth), so a test using this fails at
+ * connect time when none is configured.
+ */
+export async function withMl(
+  cb: (ml: MiddleLayer, workFolder: string) => Promise<void>,
+): Promise<void> {
+  const workFolder = path.resolve(`work/${randomUUID()}`);
+
+  await TestHelpers.withTempRoot(async (pl: PlClient) => {
+    const ml = await MiddleLayer.init(pl, workFolder, {
+      defaultTreeOptions: { pollingInterval: 250, stopPollingDelay: 500 },
+      devBlockUpdateRecheckInterval: 300,
+      localSecret: MiddleLayer.generateLocalSecret(),
+      localProjections: [],
+      openFileDialogCallback: () => {
+        throw new Error("Not implemented.");
+      },
+    });
+    ml.addRuntimeCapability("requiresUIAPIVersion", 1);
+    ml.addRuntimeCapability("requiresUIAPIVersion", 2);
+    ml.addRuntimeCapability("requiresUIAPIVersion", 3);
+    try {
+      await cb(ml, workFolder);
+    } finally {
+      await ml.close();
+    }
+  });
+}