@milaboratories/pl-middle-layer 1.71.16 → 1.72.0

package/src/middle_layer/template_list.ts

@@ -17,10 +17,10 @@ import {
 import type { TreeAndComputableU } from "./types";
 import { Computable } from "@milaboratories/computable";
 import type { MiddleLayerEnvironment } from "./middle_layer";
-import { notEmpty } from "@milaboratories/ts-helpers";
-import type { Branded, ProjectTemplateV1 } from "@milaboratories/pl-model-common";
+import type { ProjectTemplateV1, TemplateId } from "@milaboratories/pl-model-common";
+import { asTemplateId } from "@milaboratories/pl-model-common";
+import { normalizeDescription } from "@milaboratories/pl-model-middle-layer";
 import type { TemplateExportProblem } from "../model/template_export";
-import type { ShareId } from "../model/sharing_model";
 import type { AppliedEntry, TemplateApplyProblem } from "../model/template_apply";
 import type { ProjectId } from "../model/project_model";
 
@@ -30,14 +30,19 @@ export const TemplateResourceType: ResourceType = { name: "UserTemplate", versio
 
 /** Mutable: the only part of a stored template a rename may touch. */
 export const TemplateLabelKey = "TemplateLabel";
+/** Mutable: free text about the template. Absent on a template nobody described. */
+export const TemplateDescriptionKey = "TemplateDescription";
 export const TemplateCreatedTimestamp = "TemplateCreated";
 
 /**
  * Unique template identifier in middle layer, the stringified signed resource id of the
  * `UserTemplate`. Branded so it cannot be confused with a {@link ProjectId} — both are
  * stringified resource ids and every template method takes one of them.
+ *
+ * Declared in the model package because the folder document places templates as well as
+ * projects, and that document is written by code that cannot see this file.
  */
-export type TemplateId = Branded<string, "TemplateId">;
+export type { TemplateId };
 
 /**
  * Immutable `data` on a UserTemplate: the document plus what was true when it was taken.
@@ -67,6 +72,8 @@ export interface TemplateListEntry {
   id: TemplateId;
   /** The mutable label, the only part a rename changes. */
   label: string;
+  /** Free text the user wrote about the template. Absent when there is none. */
+  description?: string;
   created: Date;
   /** Number of blocks the stored document lists — derived, not stored. */
   blockCount: number;
@@ -79,9 +86,6 @@ export type SaveProjectAsTemplateOutcome =
   | { readonly ok: true; readonly templateId: TemplateId }
   | { readonly ok: false; readonly problems: readonly TemplateExportProblem[] };
 
-/** What sharing a stored template yields: the share's logical id. */
-export type ShareTemplateOutcome = { readonly shareId: ShareId };
-
 /**
  * What applying a stored template yields.
  *
@@ -143,32 +147,68 @@ export async function createTemplateList(
   const c = Computable.make((ctx) => {
     const node = ctx.accessor(tree.entry()).node();
     if (node === undefined) return undefined;
-    const result: TemplateListEntry[] = [];
-
-    // Templates list resource keeps templates assigned to fields. Each field name is a UUID
-    for (const field of node.listDynamicFields()) {
-      const tpl = node.traverse(field);
-      if (tpl === undefined) continue;
-      const data = tpl.getDataAsJson<StoredTemplateData>();
-      // A template whose data has not synced yet is not an entry with unknown content —
-      // it is an entry we cannot describe at all, so it stays out of the list until it has.
-      if (data === undefined) continue;
-      const label = notEmpty(tpl.getKeyValueAsJson<string>(TemplateLabelKey));
-      const created = notEmpty(tpl.getKeyValueAsJson<number>(TemplateCreatedTimestamp));
-      result.push({
-        id: resourceIdToString(tpl.id) as TemplateId,
-        label,
-        created: new Date(created),
-        blockCount: data.document.blocks.length,
-        ...(data.sourceProjectLabel !== undefined
-          ? { sourceProjectLabel: data.sourceProjectLabel }
-          : {}),
-        ...(data.sender !== undefined ? { sender: data.sender } : {}),
-      });
-    }
-    result.sort((a, b) => b.created.valueOf() - a.created.valueOf());
-    return result;
+    return templateListEntries(node);
   }).withStableType();
 
   return { computable: c, tree };
 }
+
+/** The part of a tree node this reader needs from a single entry of the templates list. */
+interface TemplateListEntryNode {
+  readonly id: SignedResourceId;
+  readonly resourceType: ResourceType;
+  getDataAsJson<T>(): T | undefined;
+  getKeyValueAsJson<T>(key: string): T | undefined;
+}
+
+/** The part of a tree node this reader needs from the templates-list resource itself. */
+interface TemplatesListNode {
+  listDynamicFields(): string[];
+  traverse(fieldName: string): TemplateListEntryNode | undefined;
+}
+
+/**
+ * Every stored template of one root, most recently created first.
+ *
+ * A function rather than a closure inside {@link createTemplateList} because the folder listing
+ * reads the same tree in its own computable: templates and projects share one folder tree, and
+ * joining it against two independently published lists would let a template show up in a folder
+ * the tree has not heard of.
+ *
+ * Skips, rather than throws on, anything that is not a fully synced template, by the same rule
+ * the project list follows: the folder listing is built on this, so one template whose data or
+ * label has not arrived must cost that entry and nothing else. The resource type is matched by
+ * name only, to exclude foreign resources without hiding a template stored under an earlier
+ * resource-type version.
+ */
+export function templateListEntries(node: TemplatesListNode): TemplateListEntry[] {
+  const result: TemplateListEntry[] = [];
+
+  // Templates list resource keeps templates assigned to fields. Each field name is a UUID
+  for (const field of node.listDynamicFields()) {
+    const tpl = node.traverse(field);
+    if (tpl === undefined) continue;
+    if (tpl.resourceType.name !== TemplateResourceType.name) continue;
+
+    const data = tpl.getDataAsJson<StoredTemplateData>();
+    const label = tpl.getKeyValueAsJson<string>(TemplateLabelKey);
+    const created = tpl.getKeyValueAsJson<number>(TemplateCreatedTimestamp);
+    if (data === undefined || label === undefined || created === undefined) continue;
+
+    // Written only once something is said about the template, so its absence is the ordinary case.
+    const description = normalizeDescription(tpl.getKeyValueAsJson<string>(TemplateDescriptionKey));
+    result.push({
+      id: asTemplateId(resourceIdToString(tpl.id)),
+      label,
+      ...(description === undefined ? {} : { description }),
+      created: new Date(created),
+      blockCount: data.document.blocks.length,
+      ...(data.sourceProjectLabel !== undefined
+        ? { sourceProjectLabel: data.sourceProjectLabel }
+        : {}),
+      ...(data.sender !== undefined ? { sender: data.sender } : {}),
+    });
+  }
+  result.sort((a, b) => b.created.valueOf() - a.created.valueOf());
+  return result;
+}

package/src/middle_layer/templates.test.ts

@@ -1,7 +1,6 @@
 import { expect, test } from "vitest";
-import * as tp from "node:timers/promises";
-import type { ResourceRef, SignedResourceId } from "@milaboratories/pl-client";
-import { resourceIdToString } from "@milaboratories/pl-client";
+import type { SignedResourceId } from "@milaboratories/pl-client";
+import { field, isNullSignedResourceId, resourceIdToString } from "@milaboratories/pl-client";
 import type {
   BlockKindSelectorReference,
   BlockPackLocationReference,
@@ -11,6 +10,8 @@ import type {
 import { PROJECT_TEMPLATE_SCHEMA_V1 } from "@milaboratories/pl-model-common";
 import type { BlockPackSpec } from "@milaboratories/pl-model-middle-layer";
 import type { BlockPackProvider } from "../model/template_resolve";
+import type { ShareId } from "../model/sharing_model";
+import { SharingStateField, hiddenField } from "../model/sharing_model";
 import { withMl } from "../test/with_ml";
 import { createTemplate } from "../mutator/template";
 import type { MiddleLayer } from "./middle_layer";
@@ -18,7 +19,7 @@ import type { StoredTemplateData, TemplateId, TemplateListEntry } from "./templa
 import { ensureTemplateListRid } from "./template_list";
 
 /**
- * The stored-template entity against a live backend: rename, apply, share, accept.
+ * The stored-template entity against a live backend: rename, apply, share, copy.
  *
  * Every test here stores its template directly through the mutator rather than by saving a
  * project, so the document under test is the one the test wrote — a `file:` entry, an entry
@@ -26,6 +27,10 @@ import { ensureTemplateListRid } from "./template_list";
  * produces is covered by the round trip in `drivers-ml-blocks-integration`, which has block
  * packs on disk to build one from.
  *
+ * The test server has one user, so every share here goes to everyone and is checked through
+ * what its donor can see: the outbox, the copies a share produces, and the donor's own
+ * SharingState. The recipient-side list leaves a user's own shares out.
+ *
  * Needs a backend, like every `withMl` test in this package, and no gate: `PL_ADDRESS` is
  * either configured or the client fails to connect.
  */
@@ -126,7 +131,7 @@ test("a project holding a block that cannot be written out produces no template"
   });
 });
 
-test("an accepted template share lands on the acceptor's shelf and builds nothing", async () => {
+test("copying a template share lands it among the recipient's templates and builds nothing", async () => {
   await withMl(async (ml) => {
     const stored = await storeTemplate(ml, "A pipeline", {
       schemaVersion: 1,
@@ -136,26 +141,58 @@ test("an accepted template share lands on the acceptor's shelf and builds nothin
 
     const shared = await ml.shareTemplate(stored.id, { everyone: true, title: "A pipeline" });
 
-    const outcome = await ml.acceptShare([shared.shareId]);
+    const outcome = await ml.copyShare([shared.shareId]);
 
     expect(outcome.failed).toStrictEqual([]);
-    expect(outcome.acceptedTemplates).toHaveLength(1);
+    expect(outcome.templates).toHaveLength(1);
     // Nothing is built until the recipient applies it — which is what makes an all-or-nothing
     // apply survivable for them: there is always something left to retry from.
-    expect(outcome.accepted).toStrictEqual([]);
+    expect(outcome.projects).toStrictEqual([]);
     expect(await ml.projectList.awaitStableValue()).toStrictEqual([]);
 
     const list = await awaitTemplateList(ml, (l) => l.length === 2);
-    const accepted = list.find((t) => t.id === outcome.acceptedTemplates[0])!;
-    expect(accepted.label).toBe("A pipeline");
-    // Who sent it, kept as the accepted template's provenance; the donor's own source project
-    // is not part of the payload and does not travel.
-    expect(accepted.sender).toBe(ml.currentUserLogin ?? "");
-    expect(accepted.sourceProjectLabel).toBeUndefined();
+    const copied = list.find((t) => t.id === outcome.templates[0]);
+    if (copied === undefined) throw new Error("the copied template is not in the list");
+    // The original is at the top level too, and one folder never holds two things of one name.
+    expect(copied.label).toBe("A pipeline (Copy)");
+    // Who sent it, kept as the copy's provenance; the donor's own source project is not part of
+    // the payload and does not travel.
+    expect(copied.sender).toBe(ml.currentUserLogin ?? "");
+    expect(copied.sourceProjectLabel).toBeUndefined();
+
+    // A share is a shelf, not an invitation: copying takes nothing off it, so it can be copied
+    // from again, and the second copy is named beside the first.
+    const again = await ml.copyShare([shared.shareId]);
+    expect(again.failed).toStrictEqual([]);
+    expect(again.templates).toHaveLength(1);
+    const relisted = await awaitTemplateList(ml, (l) => l.length === 3);
+    expect(relisted.find((t) => t.id === again.templates[0])?.label).toBe("A pipeline (Copy 2)");
+  });
+});
+
+test("a hidden share stays listed, flagged, until it is unhidden", async () => {
+  await withMl(async (ml) => {
+    const stored = await storeTemplate(ml, "A pipeline", {
+      schemaVersion: 1,
+      document: documentOf(entry("a")),
+    });
+
+    const shared = await ml.shareTemplate(stored.id, { everyone: true, title: "A pipeline" });
+
+    await ml.hideShare(shared.shareId);
+    // Hidden, not gone: the flag the "show hidden" view reads is written on this user's own
+    // SharingState, and nothing about the envelope changed, so the donor is none the wiser.
+    expect(await hiddenFlagWritten(ml, shared.shareId)).toBe(true);
+    const outgoing = (await ml.outgoingShares.getValue()) ?? [];
+    expect(outgoing.map((s) => s.shareId)).toStrictEqual([shared.shareId]);
+
+    // Hiding is the recipient's own choice and theirs to undo.
+    await ml.unhideShare(shared.shareId);
+    expect(await hiddenFlagWritten(ml, shared.shareId)).toBe(false);
   });
 });
 
-test("a changed template share keeps its id, and whoever already responded is not re-prompted", async () => {
+test("replacing a template share leaves one share, under a new id", async () => {
   await withMl(async (ml) => {
     const first = await storeTemplate(ml, "First", {
       schemaVersion: 1,
@@ -168,31 +205,28 @@ test("a changed template share keeps its id, and whoever already responded is no
 
     const shared = await ml.shareTemplate(first.id, { everyone: true, title: "First" });
 
-    // Someone responds to the share, which is what the replace below must not undo.
-    const accept = await ml.acceptShare([shared.shareId]);
-    expect(accept.acceptedTemplates).toHaveLength(1);
+    // Someone takes a copy, which the replace below must neither undo nor hide.
+    const copied = await ml.copyShare([shared.shareId]);
+    expect(copied.templates).toHaveLength(1);
 
-    // A stored template never changes, so an improved one is a different template — the
-    // replace names it rather than re-reading the one the share started from.
-    await ml.changeShare(shared.shareId, { templateId: second.id, title: "Second" });
+    // A stored template never changes, so an improved one is a different template and a different
+    // share. Naming the old one as replaced is what keeps the two from piling up: recipients see
+    // the improved template in place of the old one rather than beside it.
+    const replacement = await ml.shareTemplate(second.id, {
+      everyone: true,
+      title: "Second",
+      replace: [shared.shareId],
+    });
+    expect(replacement.shareId).not.toBe(shared.shareId);
 
     const outgoing = (await ml.outgoingShares.getValue()) ?? [];
-    expect((outgoing ?? []).map((s) => s.shareId)).toStrictEqual([shared.shareId]);
+    expect(outgoing.map((s) => s.shareId)).toStrictEqual([replacement.shareId]);
     expect(outgoing[0]).toMatchObject({
       payloadKind: "template",
       title: "Second",
       template: { label: "Second", blockCount: 2 },
-      // A template share is granted read-only, so no recipient can ever write a reply on the
-      // envelope — a view has to say that rather than render an empty list as "nobody yet".
-      responsesAvailable: false,
     });
     expect(outgoing[0].projects).toStrictEqual([]);
-
-    // The decision the accept recorded is keyed on the shareId, which the change preserved, so
-    // the replaced share is not offered again. A replace that minted a new id would show up
-    // here as a fresh offer.
-    const pending = await settledPendingShareIds(ml);
-    expect(pending).not.toContain(shared.shareId);
   });
 });
 
@@ -220,20 +254,19 @@ type StoredTemplate = { id: TemplateId; rid: SignedResourceId };
  *
  * The middle layer has no way to store an arbitrary document — it only saves a project — so a
  * test that needs a specific document writes it here, exactly as `saveProjectAsTemplate` and
- * the accept path do.
+ * `copyShare` do.
  */
 async function storeTemplate(
   ml: MiddleLayer,
   label: string,
   data: StoredTemplateData,
 ): Promise<StoredTemplate> {
-  let tpl: ResourceRef;
-  await ml.pl.withWriteTx("TestStoreTemplate", async (tx) => {
+  const rid = await ml.pl.withWriteTx("TestStoreTemplate", async (tx) => {
     const listRid = await ensureTemplateListRid(tx);
-    tpl = createTemplate(tx, listRid, label, data);
+    const tpl = createTemplate(tx, listRid, { label }, data);
     await tx.commit();
+    return await tpl.globalId;
   });
-  const rid = await tpl!.globalId;
   return { id: resourceIdToString(rid) as TemplateId, rid };
 }
 
@@ -265,15 +298,13 @@ async function awaitTemplateList(
   }
 }
 
-/**
- * The shareIds currently offered to this user, read after discovery has had a poll to run.
- *
- * Discovery of a just-granted envelope is a poll behind, so reading the view once would say
- * "not offered" about a share that simply had not been seen yet.
- */
-async function settledPendingShareIds(ml: MiddleLayer): Promise<string[]> {
-  await tp.setTimeout(2_000);
-  return ((await ml.pendingShares.getValue()) ?? []).map((s) => s.shareId);
+/** Whether this user's own SharingState holds the hidden flag for a share. */
+async function hiddenFlagWritten(ml: MiddleLayer, shareId: ShareId): Promise<boolean> {
+  return await ml.pl.withReadTx("TestReadShareHidden", async (tx) => {
+    const state = await tx.getField(field(tx.clientRoot, SharingStateField));
+    if (isNullSignedResourceId(state.value)) throw new Error("the SharingState was never created");
+    return (await tx.getFieldIfExists(field(state.value, hiddenField(shareId)))) !== undefined;
+  });
 }
 
 /**

package/src/model/sharing_model.test.ts

@@ -5,9 +5,11 @@ import {
   canImpersonate,
   decodeEnvelopeData,
   EnvelopeSchemaVersionCurrent,
+  envelopeFolderRoot,
   envelopeProjectMap,
   normalizeEnvelopeData,
 } from "./sharing_model";
+import type { EnvelopeFolder, EnvelopeFolderId } 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
@@ -32,9 +34,9 @@ test("canGrantToEveryone and canImpersonate does not include USER", () => {
 // 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,
+// discover envelopes (the available-shares view, the live-envelope view a copy 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.
+// envelope that does not decode cannot be offered, copied from, 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. */
@@ -102,6 +104,28 @@ test("a current envelope carrying a template decodes as one", () => {
   expect(envelopeProjectMap(data!)).toStrictEqual({});
 });
 
+test("a project carries what it said about itself through the decode", () => {
+  const projects = {
+    "9c7e4d10-2b83-4f6a-91d5-7e0c3a8b5f42": {
+      label: "Project 1",
+      source: "42",
+      updatedAt: 1_700_000_000_000,
+      description: "Donor 14, both replicates",
+    },
+  };
+  const data = decodeEnvelopeData(
+    blob({
+      ...v1Envelope,
+      schemaVersion: EnvelopeSchemaVersionCurrent,
+      projects: undefined,
+      payload: { kind: "projects", projects },
+    }),
+  );
+  if (data === undefined) throw new Error("a current envelope of projects must decode");
+
+  expect(envelopeProjectMap(data)).toStrictEqual(projects);
+});
+
 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.
@@ -134,3 +158,46 @@ test("anything that is not an envelope object does not decode", () => {
   expect(normalizeEnvelopeData("an envelope")).toBeUndefined();
   expect(normalizeEnvelopeData(42)).toBeUndefined();
 });
+
+test("a folder envelope decodes, and its root is the folder with no parent", () => {
+  const folders: Record<string, EnvelopeFolder> = {
+    a: { name: "Repertoires" },
+    b: { name: "2024", parent: "a" as EnvelopeFolderId },
+  };
+
+  const decoded = decodeEnvelopeData(
+    blob({
+      ...v1Envelope,
+      schemaVersion: EnvelopeSchemaVersionCurrent,
+      projects: undefined,
+      payload: {
+        kind: "folder",
+        source: "f1",
+        folders,
+        projects: {},
+        templates: [],
+        from: "someone",
+      },
+    }),
+  );
+  if (decoded?.payload.kind !== "folder") throw new Error("a folder envelope must decode as one");
+
+  // The root is found on what came out of the decode, so the subtree survived it intact.
+  expect(decoded.payload.folders).toStrictEqual(folders);
+  expect(envelopeFolderRoot(decoded.payload.folders)).toBe("a");
+});
+
+test("a folder envelope with no single root describes no subtree", () => {
+  const twoRoots: Record<string, EnvelopeFolder> = {
+    a: { name: "One" },
+    b: { name: "Two" },
+  };
+  const noRoot: Record<string, EnvelopeFolder> = {
+    a: { name: "One", parent: "b" as EnvelopeFolderId },
+    b: { name: "Two", parent: "a" as EnvelopeFolderId },
+  };
+  // Rebuilding would have to guess which folder was shared; the copy refuses instead.
+  expect(envelopeFolderRoot(twoRoots)).toBeUndefined();
+  expect(envelopeFolderRoot(noRoot)).toBeUndefined();
+  expect(envelopeFolderRoot({})).toBeUndefined();
+});