@milaboratories/pl-middle-layer 1.68.2 → 1.69.0

package/dist/middle_layer/middle_layer.d.ts

@@ -1,10 +1,12 @@
 import { V2RegistryProvider } from "../block_registry/registry-v2-provider.js";
 import { TemplateApplyReport } from "../model/template_apply.js";
-import { BlockPackProvider } from "../model/template_resolve.js";
+import { BlockPackProvider, TemplateResolveOutcome } from "../model/template_resolve.js";
 import "../block_registry/index.js";
 import { ProjectId as ProjectId$1, ProjectListEntry as ProjectListEntry$1 } from "../model/project_model.js";
+import { TemplateShareProblem } from "../model/template_share.js";
+import { ProjectChangeAction, ShareId, ShareProjectsOptions, ShareTemplateOptions } from "../model/sharing_model.js";
+import { CreateProjectFromTemplateOutcome, SaveProjectAsTemplateOutcome, ShareTemplateOutcome, StoredTemplateData, TemplateId, TemplateListEntry } from "./template_list.js";
 import { ProjectTemplateExportOutcome } from "../model/template_serializer.js";
-import { ProjectChangeAction, ShareId, ShareProjectsOptions } from "../model/sharing_model.js";
 import { OutgoingShare, PendingShare } from "./sharing_list.js";
 import "../model/index.js";
 import { BlockPackPreparer } from "../mutator/block-pack/block_pack.js";
@@ -62,16 +64,20 @@ export declare class MiddleLayer {
   readonly driverKit: DriverKit;
   readonly signer: Signer;
   private readonly projectListResourceId;
+  private readonly templateListResourceId;
   private readonly sharingOutboxResourceId;
   private readonly sharingStateResourceId;
   private readonly openedProjectsList;
   private readonly projectListTree;
+  private readonly templateListTree;
   private readonly sharingOutboxTree;
   private readonly sharingStateTree;
   private readonly pendingSharesTree;
   readonly blockRegistryProvider: V2RegistryProvider;
   /** Contains a reactive list of projects along with their meta information. */
   readonly projectList: ComputableStableDefined<ProjectListEntry$1[]>;
+  /** Contains a reactive list of stored templates along with their labels and provenance. */
+  readonly templateList: ComputableStableDefined<TemplateListEntry[]>;
   /** Reactive view of the donor's outbox — the shares this user has created.
    *  v1: API only, no UI. */
   outgoingShares: Computable<OutgoingShare[] | undefined>;
@@ -209,6 +215,70 @@ export declare class MiddleLayer {
     allowUnstable?: boolean;
     author?: AuthorMarker;
   }): Promise<TemplateApplyReport>;
+  /**
+   * Stages 1 and 2 of an apply — resolve every entry to a block pack, then prepare every
+   * block — for a document that may not have a project yet.
+   *
+   * Neither stage creates anything, which is what lets a caller run them before it decides to
+   * create a project at all: {@link createProjectFromTemplate} does exactly that, so an
+   * unapplicable template leaves no empty project behind.
+   */
+  private prepareTemplateEntries;
+  /**
+   * Stage 3 of an apply — create the blocks in one transaction, all or nothing.
+   *
+   * An entry it cannot create throws, the transaction is never committed, and the project keeps
+   * none of the blocks the apply had placed.
+   */
+  private applyPreparedEntries;
+  private readonly templateIdCache;
+  /**
+   * Saves a project as a template: a snapshot of its blocks and their params, no data.
+   *
+   * The document the export produced is what gets stored; the YAML it also rendered is a
+   * file format, and a stored template is rendered to it only on download.
+   *
+   * A block that cannot be expressed as a template entry stores nothing at all, and every
+   * such block is reported — fixing an unexportable project takes one pass, not one per block.
+   *
+   * @param projectId project to snapshot
+   * @param label label for the template; defaults to the project's own label
+   */
+  saveProjectAsTemplate(projectId: ProjectId$1, label?: string): Promise<SaveProjectAsTemplateOutcome>;
+  /** Changes a template's label. The stored document is immutable and stays untouched —
+   *  improving a template means saving a new one. */
+  renameTemplate(id: TemplateId, label: string): Promise<void>;
+  /** Permanently deletes a template from the template list. */
+  deleteTemplate(id: TemplateId): Promise<void>;
+  /** Reads a stored template: its document plus what was true when it was taken. */
+  getTemplateData(id: TemplateId): Promise<StoredTemplateData>;
+  /**
+   * Where each entry of a stored template would get its block from, and which entries have
+   * nowhere to get one — resolution creates nothing, so this is the preview a UI shows before
+   * offering Apply. {@link createProjectFromTemplate} runs the same stage itself.
+   */
+  resolveTemplate(id: TemplateId, provider: BlockPackProvider, options?: {
+    allowUnstable?: boolean;
+  }): Promise<TemplateResolveOutcome>;
+  /**
+   * Creates one project holding every block the stored template lists, in the template's order.
+   *
+   * Resolution and preparation run before the project exists, so a template with an entry
+   * nothing can supply a block for leaves no empty project in the list. The one write that
+   * follows is all or nothing, and an entry it rejects takes the project with it.
+   *
+   * @param id template to apply
+   * @param label label for the new project
+   * @param provider where each entry's block comes from
+   * @param options `allowUnstable` widens resolution to pre-release implementations
+   */
+  createProjectFromTemplate(id: TemplateId, label: string, provider: BlockPackProvider, options?: {
+    allowUnstable?: boolean;
+    author?: AuthorMarker;
+  }): Promise<CreateProjectFromTemplateOutcome>;
+  /** Resolves a TemplateId to a signed SignedResourceId.
+   * Uses LRU cache with TX-scan fallback. */
+  private resolveTemplateId;
   /** Permanently deletes project from the project list, this will result in
    * destruction of all attached objects, like files, analysis results etc. */
   deleteProject(id: ProjectId$1): Promise<void>;
@@ -251,6 +321,42 @@ export declare class MiddleLayer {
    * the mint-a-new-envelope branch.
    */
   private createNewShare;
+  /**
+   * Grants one freshly built envelope inside the transaction that created it: a single make-public
+   * grant for an everyone-share (empty/ignored target, ANY_AUTHORISED — the backend rewrites the
+   * target to the everyone-user, gated by role + permission ceiling), or one grant per named
+   * recipient.
+   *
+   * `writable` is not a preference. A project pack needs a writable grant because accepting copies
+   * the snapshots out of the envelope, and the cross-color attach rule permits that only to a
+   * writable grant holder. A template share copies nothing — the document sits in the envelope's
+   * own immutable data — so it is granted read-only, and must be: a writable everyone-grant would
+   * hand every user on the server write access to the envelope.
+   */
+  private grantShareEnvelope;
+  /**
+   * Shares one stored template. The envelope carries the document itself, so there is no project
+   * snapshot and no resource for the recipient to copy out — which is why the grant is read-only.
+   * The cost of that is the donor's receipt: nobody can write an acceptance onto a read-only
+   * envelope, so a template share never reports who accepted it.
+   *
+   * A template holding a block installed from a folder on this machine is refused rather than sent,
+   * with every offending entry named. {@link checkTemplateShareable} answers the same question
+   * without attempting the share, so a UI can state it on the template itself.
+   *
+   * @param id template to share
+   * @param options recipients XOR everyone, plus the title recipients see
+   */
+  shareTemplate(id: TemplateId, options: ShareTemplateOptions): Promise<ShareTemplateOutcome>;
+  /**
+   * Every entry of a stored template that stands in the way of sharing it, empty for a template
+   * that can be shared. Reads the template and nothing else, so a UI can state the refusal on the
+   * template itself instead of only when the user tries to share it.
+   */
+  checkTemplateShareable(id: TemplateId): Promise<readonly TemplateShareProblem[]>;
+  /** The document and the label of a template that may be shared, or every entry that stops it.
+   *  The label is what the recipient's own list will show, so it travels with the document. */
+  private loadShareableTemplate;
   /**
    * Changes a share in place (same {@link ShareId}), in one write transaction: re-snapshots live
    * source projects and carries deleted ones' snapshots forward; applies edited recipients/title;
@@ -266,12 +372,19 @@ export declare class MiddleLayer {
    * existing snapshot (and its timestamp), `remove` drops the project from the pack. A project not
    * in the map defaults to `keep`. Omit the whole map for the legacy auto behavior (live sources
    * updated, gone ones kept) — the everyone-refresh path relies on that.
+   *
+   * `opts.templateId` is required for, and only used by, a share that carries a template: a stored
+   * template is immutable, so an improved one is a different template and the share cannot re-read
+   * the one it started from — the caller names the new target. Every other option means the same
+   * thing for both kinds of share. Sharing the named template must be permitted (see
+   * {@link checkTemplateShareable}) or this throws.
    */
   changeShare(shareId: ShareId, opts?: {
     recipients?: string[];
     everyone?: boolean;
     title?: string;
     projectActions?: Record<ProjectId$1, ProjectChangeAction>;
+    templateId?: TemplateId;
   }): Promise<void>;
   /**
    * Finds the donor's own outgoing envelopes built from any of the given source projects —
@@ -305,16 +418,21 @@ export declare class MiddleLayer {
    */
   private resolveLiveEnvelopes;
   /**
-   * Accepts one or more pending shares: duplicates each share's projects into this user's
-   * project list, records the decision per share, and (read-write share) writes the donor-visible
-   * acceptance onto the envelope. Per-share failures (e.g. an expiry race) are collected, not
-   * short-circuited — the rest still get accepted. Accept-all = pass every current pending shareId.
+   * Accepts one or more pending shares. What accepting does depends on what the share carries: a
+   * pack of projects is duplicated into this user's project list, while a template is added to this
+   * user's own template list and builds nothing — the recipient decides later whether to apply it.
+   * Either way the decision is recorded per share, and a read-write share also gets the
+   * donor-visible acceptance written onto its envelope. Per-share failures (e.g. an expiry race)
+   * are collected, not short-circuited — the rest still get accepted. Accept-all = pass every
+   * current pending shareId.
    *
    * `rename` resolves label collisions (same callback contract as {@link duplicateProject}), but
-   * the source lives in the envelope tree, so accept calls the low-level mutator directly.
+   * the source lives in the envelope tree, so accept calls the low-level mutator directly. It does
+   * not apply to a template share, whose label is not required to be unique.
    */
   acceptShare(shareIds: ShareId[], rename?: (previousLabel: string, existingLabels: string[]) => string): Promise<{
     accepted: ProjectId$1[];
+    acceptedTemplates: TemplateId[];
     failed: {
       shareId: ShareId;
       error: string;

package/dist/middle_layer/middle_layer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middle_layer.d.ts","names":[],"sources":["../../src/middle_layer/middle_layer.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;iBAyHiB;EACf,WAAW;WACF,IAAI;WACJ,qBAAqB;WACrB,QAAQ;WACR,sBAAsB;WACtB,gBAAgB;WAChB,qBAAqB;WACrB,QAAQ;WACR,KAAK;WACL,YAAY;WACZ,wBAAwB;WACxB,oBAAoB;WACpB,SAAS;WACT,WAAW;WACX,iBAAiB;WACjB,eAAe;;;WAGf,gBAAgB;;;;;;;;;;;;;;qBAed;mBAIQ;WACD,WAAW;WACX,QAAQ;mBACP;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;WACD,uBAAuB;;WAEvB,aAAa,wBAAwB;;;EAG9C,gBAAgB,WAAW;;;EAG3B,eAAe,WAAW;;;;mBAIhB;WA1BH,IAAI;UAEb;;;;;MAkCI,kBAAkB;;;;;;;MAUlB;;;;;MAQA;;;;;;;MAUA;;MAQA;;;;;MAQA,mBAAmB;;;;;;;MAUnB;;;;;;;;MAeA;;EAKJ,qBACL,aAAa,sBACb;;EAMK,wBAAwB,cAAc;;MAKlC,qBAAqB;;MAKrB,mBAAmB;mBAQb;;;UAIH;;EAuBD,cAAc,MAAM,cAAc,QAAQ;;EAgB1C,eACX,IAAI,aACJ,MAAM,aACN,SAAS,eACR;;;;;;;;;;;;;;;;EA8BU,wBAAwB,IAAI,cAAY,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsDhD,uBACX,IAAI,aACJ,UAAU,mBACV,UAAU,mBACV;IAAW;IAAyB,SAAS;MAC5C,QAAQ;;;EAsGE,cAAc,IAAI,cAAY;;;;;;;;EA0B9B,iBACX,cAAc,aACd,UAAU,uBAAuB,sCAChC,QAAQ;;;;;;;;;EAoDE,uBACX,cAAc,aACd,qBACA,UAAU,uBAAuB,sCAChC;;;;;;;;;;;;;;EAsDU,cACX,YAAY,eACZ,SAAS,uBACR;;;;;;;;UA0BW;;;;;;;;;;;;;;;;;EAuFD,YACX,SAAS,SACT;IACE;IACA;IACA;IACA,iBAAiB,OAAO,aAAW;MAEpC;;;;;;;UA6GW;;;;;;EA4CD,YAAY,SAAS,UAAU;;;;;;;UAiB9B;;;;;;;;;;;UAyBA;;;;;;;;;;EAkBD,YACX,UAAU,WACV,UAAU,uBAAuB,sCAChC;IAAU,UAAU;IAAa;MAAU,SAAS;MAAS;;;;EAqDnD,YAAY,SAAS,UAAU;0BA4BpB;UAChB;;UAGA;;;UAWM;mBAqCG;;;mBAIA;UAET;;;;;;;UAWM;;EAgBD,YAAY,IAAI,cAAY;;EAQ5B,aAAa,IAAI,cAAY;;EAmBnC,iBAAiB,IAAI,cAAY;;EAOjC,gBAAgB,IAAI;;;;MAOhB,qBAAqB,SAAS;;;;;;EAS5B,SAAK;;EAgBL,4BAAwB;;;SAMvB;;MAKH,wBAAwB;;SAKf,KAClB,IAAI,UACJ,iBACA,MAAM,4BACL,QAAQ"}
+{"version":3,"file":"middle_layer.d.ts","names":[],"sources":["../../src/middle_layer/middle_layer.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8IiB;EACf,WAAW;WACF,IAAI;WACJ,qBAAqB;WACrB,QAAQ;WACR,sBAAsB;WACtB,gBAAgB;WAChB,qBAAqB;WACrB,QAAQ;WACR,KAAK;WACL,YAAY;WACZ,wBAAwB;WACxB,oBAAoB;WACpB,SAAS;WACT,WAAW;WACX,iBAAiB;WACjB,eAAe;;;WAGf,gBAAgB;;;;;;;;;;;;;;qBAed;mBAIQ;WACD,WAAW;WACX,QAAQ;mBACP;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;WACD,uBAAuB;;WAEvB,aAAa,wBAAwB;;WAErC,cAAc,wBAAwB;;;EAG/C,gBAAgB,WAAW;;;EAG3B,eAAe,WAAW;;;;mBAIhB;WA9BH,IAAI;UAEb;;;;;MAsCI,kBAAkB;;;;;;;MAUlB;;;;;MAQA;;;;;;;MAUA;;MAQA;;;;;MAQA,mBAAmB;;;;;;;MAUnB;;;;;;;;MAeA;;EAKJ,qBACL,aAAa,sBACb;;EAMK,wBAAwB,cAAc;;MAKlC,qBAAqB;;MAKrB,mBAAmB;mBAQb;;;UAIH;;EAuBD,cAAc,MAAM,cAAc,QAAQ;;EAgB1C,eACX,IAAI,aACJ,MAAM,aACN,SAAS,eACR;;;;;;;;;;;;;;;;EA8BU,wBAAwB,IAAI,cAAY,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsDhD,uBACX,IAAI,aACJ,UAAU,mBACV,UAAU,mBACV;IAAW;IAAyB,SAAS;MAC5C,QAAQ;;;;;;;;;UAgBG;;;;;;;UAiFA;mBA0CG;;;;;;;;;;;;;EAcJ,sBACX,WAAW,aACX,iBACC,QAAQ;;;EAyBE,eAAe,IAAI,YAAY,gBAAgB;;EAU/C,eAAe,IAAI,aAAa;;EAUhC,gBAAgB,IAAI,aAAa,QAAQ;;;;;;EAczC,gBACX,IAAI,YACJ,UAAU,mBACV;IAAW;MACV,QAAQ;;;;;;;;;;;;;EAmBE,0BACX,IAAI,YACJ,eACA,UAAU,mBACV;IAAW;IAAyB,SAAS;MAC5C,QAAQ;;;UA2BG;;;EAoBD,cAAc,IAAI,cAAY;;;;;;;;EA0B9B,iBACX,cAAc,aACd,UAAU,uBAAuB,sCAChC,QAAQ;;;;;;;;;EAoDE,uBACX,cAAc,aACd,qBACA,UAAU,uBAAuB,sCAChC;;;;;;;;;;;;;;EAsDU,cACX,YAAY,eACZ,SAAS,uBACR;;;;;;;;UA0BW;;;;;;;;;;;;;UA2EA;;;;;;;;;;;;;;EAyBD,cACX,IAAI,YACJ,SAAS,uBACR,QAAQ;;;;;;EAiCE,uBAAuB,IAAI,aAAa,iBAAiB;;;UAOxD;;;;;;;;;;;;;;;;;;;;;;;EA2CD,YACX,SAAS,SACT;IACE;IACA;IACA;IACA,iBAAiB,OAAO,aAAW;IACnC,aAAa;MAEd;;;;;;;UAkJW;;;;;;EA6CD,YAAY,SAAS,UAAU;;;;;;;UAiB9B;;;;;;;;;;;UA0BA;;;;;;;;;;;;;;EAsBD,YACX,UAAU,WACV,UAAU,uBAAuB,sCAChC;IACD,UAAU;IACV,mBAAmB;IACnB;MAAU,SAAS;MAAS;;;;EAyFjB,YAAY,SAAS,UAAU;0BA4BpB;UAChB;;UAGA;;;UAWM;mBAsCG;;;mBAIA;UAET;;;;;;;UAWM;;EAgBD,YAAY,IAAI,cAAY;;EAQ5B,aAAa,IAAI,cAAY;;EAmBnC,iBAAiB,IAAI,cAAY;;EAOjC,gBAAgB,IAAI;;;;MAOhB,qBAAqB,SAAS;;;;;;EAS5B,SAAK;;EAiBL,4BAAwB;;;SAMvB;;MAKH,wBAAwB;;SAKf,KAClB,IAAI,UACJ,iBACA,MAAM,4BACL,QAAQ"}