@monosmith/plugin-sdk 2.0.0-beta.7 → 2.0.0-beta.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monosmith/plugin-sdk",
-  "version": "2.0.0-beta.7",
+  "version": "2.0.0-beta.9",
   "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

@@ -2047,7 +2047,14 @@ export const protocolSchema = {
                 },
                 "propagationWait": {
                     "type": "string",
-                    "description": "PropagationWait is the longest time a plugin waits, before it moves a dist-tag, 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."
+                    "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": [
@@ -2075,12 +2082,19 @@ 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."
                 },
-                "pendingTags": {
+                "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": "PendingTags are the exact commands that move the dist-tags the publish did not move, because the packages the release needs were not fetchable yet. The release then ends with a warning, never silently."
+                    "description": "Moved names the dist-tags a Finalize call moved (\"name@version tag\")."
                 },
                 "assets": {
                     "type": "array",
@@ -2490,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",
@@ -2561,7 +2605,7 @@ export const protocolSchema = {
             ]
         },
         "ToolInstall": {
-            "description": "ToolInstall is one way to get a tool with a package manager. Manager is one of: \"winget\", \"brew\", \"brew-cask\", \"apt\", \"dnf\", \"pacman\", \"npm\", \"uv\", \"fnm\" and \"rustup\". The host builds the exact command from the manager and Package; Package may hold {major} and {major.minor}, which the pinned or suggested version fills. The language's own installers (uv, fnm, rustup) are offered only when they are already on the machine.",
+            "description": "ToolInstall is one way to get a tool with a package manager. Manager is one of: \"winget\", \"brew\", \"brew-cask\", \"apt\", \"dnf\", \"pacman\", \"npm\", \"uv\", \"fnm\", \"rustup\" and \"cargo\". The host builds the exact command from the manager and Package; Package may hold {major} and {major.minor}, which the pinned or suggested version fills. The language's own installers (uv, fnm, rustup, cargo) are offered only when they are already on the machine.",
             "type": "object",
             "properties": {
                 "manager": {

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

@@ -1092,11 +1092,17 @@ export interface PublishParams {
      */
     tag?: string;
     /**
-     * PropagationWait is the longest time a plugin waits, before it moves a dist-tag, 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.
+     * 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
@@ -1112,11 +1118,14 @@ export interface PublishResult {
      */
     notes?: string[];
     /**
-     * PendingTags are the exact commands that move the dist-tags the publish did not move, because
-     * the packages the release needs were not fetchable yet. The release then ends with a warning,
-     * never silently.
+     * 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.
      */
-    pendingTags?: string[];
+    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.
@@ -1320,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. */
@@ -1365,10 +1387,10 @@ export interface Task {
 }
 /**
  * ToolInstall is one way to get a tool with a package manager. Manager is one of: "winget", "brew",
- * "brew-cask", "apt", "dnf", "pacman", "npm", "uv", "fnm" and "rustup". The host builds the exact
- * command from the manager and Package; Package may hold {major} and {major.minor}, which the
- * pinned or suggested version fills. The language's own installers (uv, fnm, rustup) are offered
- * only when they are already on the machine.
+ * "brew-cask", "apt", "dnf", "pacman", "npm", "uv", "fnm", "rustup" and "cargo". The host builds
+ * the exact command from the manager and Package; Package may hold {major} and {major.minor}, which
+ * the pinned or suggested version fills. The language's own installers (uv, fnm, rustup, cargo) are
+ * offered only when they are already on the machine.
  */
 export interface ToolInstall {
     manager: string;