@monosmith/plugin-sdk 2.0.0-beta.6 → 2.0.0-beta.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monosmith/plugin-sdk",
-  "version": "2.0.0-beta.6",
+  "version": "2.0.0-beta.8",
   "description": "The TypeScript SDK for writing smith plugins: the protocol's types, the serve loop, a test host, the conformance checks, templating and key-order-keeping JSON editing. No runtime dependencies.",
   "license": "MIT",
   "type": "module",

package/protocol/protocol-schema.contract.js

@@ -2044,6 +2044,17 @@ export const protocolSchema = {
                 "tag": {
                     "type": "string",
                     "description": "Tag is the name of the release channel the version belongs to (npm's dist-tag \"beta\"). When set, the plugin publishes under it and leaves the registry's stable pointer where it is, or ignores it when its registry has no such pointer. Only sent to a plugin with the channels capability."
+                },
+                "propagationWait": {
+                    "type": "string",
+                    "description": "PropagationWait is the longest time a plugin waits, in a Finalize call, for the packages of the release to be fetchable from the registry: a duration such as \"15m\", \"0\" to not wait. Empty means the default. Only npm has such a wait. A publish never waits."
+                },
+                "finalize": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/TagMove"
+                    },
+                    "description": "Finalize turns the call into the last phase of a release: nothing is published; for each move the plugin waits until its packages are fetchable, then moves the dist-tag. The host sends it after every project has published, so a wait never blocks another publish."
                 }
             },
             "required": [
@@ -2071,6 +2082,20 @@ export const protocolSchema = {
                     },
                     "description": "Notes are things the person must know about a publish that succeeded, such as a dist-tag that was not moved; the host prints them and the report keeps them."
                 },
+                "pendingMoves": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/TagMove"
+                    },
+                    "description": "PendingMoves are the dist-tags the call did not move, because the packages the release needs were not fetchable yet. A publish returns them for the host to move at the end of the release; a Finalize call returns the ones still waiting when its time ran out. The release then ends with a warning, never silently."
+                },
+                "moved": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Moved names the dist-tags a Finalize call moved (\"name@version tag\")."
+                },
                 "assets": {
                     "type": "array",
                     "items": {
@@ -2479,6 +2504,36 @@ export const protocolSchema = {
                 "blocking"
             ]
         },
+        "TagMove": {
+            "description": "TagMove is a dist-tag a publish left where it was, because the packages the release needs were not fetchable yet.",
+            "type": "object",
+            "properties": {
+                "package": {
+                    "type": "string",
+                    "description": "Package and Version name the package that carries the tag."
+                },
+                "version": {
+                    "type": "string"
+                },
+                "tag": {
+                    "type": "string",
+                    "description": "Tag is the dist-tag to move to Version."
+                },
+                "awaits": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Awaits are the packages that must be fetchable first."
+                }
+            },
+            "required": [
+                "package",
+                "version",
+                "tag",
+                "awaits"
+            ]
+        },
         "Task": {
             "description": "Task is a command the host can run, hash and cache.",
             "type": "object",

package/protocol/protocol-types.contract.d.ts

@@ -1091,6 +1091,18 @@ export interface PublishParams {
      * capability.
      */
     tag?: string;
+    /**
+     * PropagationWait is the longest time a plugin waits, in a Finalize call, for the packages of the
+     * release to be fetchable from the registry: a duration such as "15m", "0" to not wait. Empty
+     * means the default. Only npm has such a wait. A publish never waits.
+     */
+    propagationWait?: string;
+    /**
+     * Finalize turns the call into the last phase of a release: nothing is published; for each move
+     * the plugin waits until its packages are fetchable, then moves the dist-tag. The host sends it
+     * after every project has published, so a wait never blocks another publish.
+     */
+    finalize?: TagMove[];
 }
 /**
  * PublishResult reports what happened. Skipped with a reason is a success: an already-published
@@ -1105,6 +1117,15 @@ export interface PublishResult {
      * was not moved; the host prints them and the report keeps them.
      */
     notes?: string[];
+    /**
+     * PendingMoves are the dist-tags the call did not move, because the packages the release needs
+     * were not fetchable yet. A publish returns them for the host to move at the end of the release;
+     * a Finalize call returns the ones still waiting when its time ran out. The release then ends
+     * with a warning, never silently.
+     */
+    pendingMoves?: TagMove[];
+    /** Moved names the dist-tags a Finalize call moved ("name@version tag"). */
+    moved?: string[];
     /**
      * Assets are the workspace-relative files built for the release, in upload order; in a dry run,
      * the files that would be built.
@@ -1308,6 +1329,19 @@ export interface Step {
      */
     cacheFiles?: string[];
 }
+/**
+ * TagMove is a dist-tag a publish left where it was, because the packages the release needs were
+ * not fetchable yet.
+ */
+export interface TagMove {
+    /** Package and Version name the package that carries the tag. */
+    package: string;
+    version: string;
+    /** Tag is the dist-tag to move to Version. */
+    tag: string;
+    /** Awaits are the packages that must be fetchable first. */
+    awaits: string[];
+}
 /** Task is a command the host can run, hash and cache. */
 export interface Task {
     /** Command is an argv array; it is never passed through a shell. */