@monosmith/plugin-sdk 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monosmith/plugin-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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

@@ -131,6 +131,17 @@ export const protocolSchema = {
             "capability": "remove",
             "notification": false
         },
+        "project/kind": {
+            "description": "Asks what changing a project between app, lib and package edits: its manifest, the workspace files and the dependents that name its kind or directory. The host applies the edits and moves the directory.",
+            "params": {
+                "$ref": "#/$defs/ChangeKindParams"
+            },
+            "result": {
+                "$ref": "#/$defs/ChangeKindResult"
+            },
+            "capability": "changeKind",
+            "notification": false
+        },
         "published": {
             "description": "Asks which version of a project its registry has, so a release can check its tags against it.",
             "params": {
@@ -497,6 +508,10 @@ export const protocolSchema = {
                     "type": "boolean",
                     "description": "Remove cleans up a removed project's traces outside its directory."
                 },
+                "changeKind": {
+                    "type": "boolean",
+                    "description": "ChangeKind answers what changing a project's kind edits (smith kind)."
+                },
                 "published": {
                     "type": "boolean",
                     "description": "Published reports what a registry has of a project."
@@ -519,6 +534,60 @@ export const protocolSchema = {
                 }
             }
         },
+        "ChangeKindParams": {
+            "description": "ChangeKindParams asks a plugin what changing a project's kind edits. The plugin writes nothing: it answers with the files' new contents, and the host applies them, then moves the project's directory.",
+            "type": "object",
+            "properties": {
+                "project": {
+                    "$ref": "#/$defs/Project",
+                    "description": "Project is the project as it is now."
+                },
+                "to": {
+                    "$ref": "#/$defs/ProjectKind",
+                    "description": "To is the kind it becomes."
+                },
+                "newRoot": {
+                    "type": "string",
+                    "description": "NewRoot is the workspace-relative directory the host moves the project to afterwards; it equals Project.Root when the directory stays."
+                },
+                "projects": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/Project"
+                    },
+                    "description": "Projects are every project of the workspace, so the plugin can find the ones whose manifests and sources name this one."
+                }
+            },
+            "required": [
+                "project",
+                "to",
+                "newRoot"
+            ]
+        },
+        "ChangeKindResult": {
+            "description": "ChangeKindResult is what the change edits. Every path in Files is the path the file has before the move.",
+            "type": "object",
+            "properties": {
+                "refused": {
+                    "type": "string",
+                    "description": "Refused says why this kind makes no sense for the project's language (\"a Bicep template is deployed, never published\"); the host stops and shows it. Empty when the change is fine."
+                },
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/FileEdit"
+                    },
+                    "description": "Files are the edits: manifests, workspace files and dependents that name the project's kind or its directory."
+                },
+                "warnings": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Warnings name what the change loses or leaves for the user (a binary an app has and a lib does not, a lockfile to refresh)."
+                }
+            }
+        },
         "ContributeParams": {
             "description": "ContributeParams hands a plugin the projects it applies to: those whose stack includes it, or, for a workspace-wide convention, those of the languages it supports that smith.toml enables it for.",
             "type": "object",
@@ -990,6 +1059,10 @@ export const protocolSchema = {
                         "type": "string"
                     },
                     "description": "Notes are printed to the user after generation."
+                },
+                "installPending": {
+                    "type": "boolean",
+                    "description": "InstallPending is true when the plugin changed what the workspace depends on and left installing it to the host. A project is made by several plugins in turn; the host asks each plugin that reported this to install once (dependencies/install with Quiet set) after the last of them has generated, instead of once per plugin."
                 }
             },
             "required": [
@@ -1140,6 +1213,10 @@ export const protocolSchema = {
                 "dev": {
                     "type": "boolean",
                     "description": "Dev adds them as development dependencies where the ecosystem has such a thing; a plugin without one says so in a note."
+                },
+                "quiet": {
+                    "type": "boolean",
+                    "description": "Quiet keeps the package manager's output unless it fails: the host sets it when it installs as one step of a larger job (smith add)."
                 }
             }
         },
@@ -1333,6 +1410,10 @@ export const protocolSchema = {
                 "registries": {
                     "$ref": "#/$defs/Registries",
                     "description": "Registries are the private registries the project installs from and publishes to, from smith.toml [registries]; nil means the public ones. Set by the host."
+                },
+                "releaseAssets": {
+                    "$ref": "#/$defs/AssetSpec",
+                    "description": "ReleaseAssets is what an app's release builds, from smith.toml [projects.<project>.release]: the platforms and file names, so a plugin can check (doctor) and prepare (CI) for them. Nil for a project that has no release files. Set by the host."
                 }
             },
             "required": [

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

@@ -144,6 +144,8 @@ export interface Capabilities {
     contribute?: boolean;
     /** Remove cleans up a removed project's traces outside its directory. */
     remove?: boolean;
+    /** ChangeKind answers what changing a project's kind edits (smith kind). */
+    changeKind?: boolean;
     /** Published reports what a registry has of a project. */
     published?: boolean;
     /** Dependencies installs and uninstalls packages in its projects. */
@@ -159,6 +161,48 @@ export interface Capabilities {
      */
     cancel?: boolean;
 }
+/**
+ * ChangeKindParams asks a plugin what changing a project's kind edits. The plugin writes nothing:
+ * it answers with the files' new contents, and the host applies them, then moves the project's
+ * directory.
+ */
+export interface ChangeKindParams {
+    /** Project is the project as it is now. */
+    project: Project;
+    /** To is the kind it becomes. */
+    to: ProjectKind;
+    /**
+     * NewRoot is the workspace-relative directory the host moves the project to afterwards; it equals
+     * Project.Root when the directory stays.
+     */
+    newRoot: string;
+    /**
+     * Projects are every project of the workspace, so the plugin can find the ones whose manifests
+     * and sources name this one.
+     */
+    projects?: Project[];
+}
+/**
+ * ChangeKindResult is what the change edits. Every path in Files is the path the file has before
+ * the move.
+ */
+export interface ChangeKindResult {
+    /**
+     * Refused says why this kind makes no sense for the project's language ("a Bicep template is
+     * deployed, never published"); the host stops and shows it. Empty when the change is fine.
+     */
+    refused?: string;
+    /**
+     * Files are the edits: manifests, workspace files and dependents that name the project's kind or
+     * its directory.
+     */
+    files?: FileEdit[];
+    /**
+     * Warnings name what the change loses or leaves for the user (a binary an app has and a lib does
+     * not, a lockfile to refresh).
+     */
+    warnings?: string[];
+}
 /**
  * ContributeParams hands a plugin the projects it applies to: those whose stack includes it, or,
  * for a workspace-wide convention, those of the languages it supports that smith.toml enables it
@@ -389,6 +433,13 @@ export interface GenerateResult {
     files: string[];
     /** Notes are printed to the user after generation. */
     notes?: string[];
+    /**
+     * InstallPending is true when the plugin changed what the workspace depends on and left
+     * installing it to the host. A project is made by several plugins in turn; the host asks each
+     * plugin that reported this to install once (dependencies/install with Quiet set) after the last
+     * of them has generated, instead of once per plugin.
+     */
+    installPending?: boolean;
 }
 /** InitializeParams is sent once, first, by the host. */
 export interface InitializeParams {
@@ -469,6 +520,11 @@ export interface InstallParams {
      * without one says so in a note.
      */
     dev?: boolean;
+    /**
+     * Quiet keeps the package manager's output unless it fails: the host sets it when it installs as
+     * one step of a larger job (smith add).
+     */
+    quiet?: boolean;
 }
 /**
  * LatestParams asks for the newest stable release of each dependency, and, with Tools, how the
@@ -599,6 +655,12 @@ export interface Project {
      * smith.toml [registries]; nil means the public ones. Set by the host.
      */
     registries?: Registries;
+    /**
+     * ReleaseAssets is what an app's release builds, from smith.toml [projects.<project>.release]:
+     * the platforms and file names, so a plugin can check (doctor) and prepare (CI) for them. Nil for
+     * a project that has no release files. Set by the host.
+     */
+    releaseAssets?: AssetSpec;
 }
 /**
  * ProjectKind is the universal kind vocabulary.
@@ -1007,6 +1069,16 @@ export interface ProtocolMethods {
         result: RemoveResult;
         capability: 'remove';
     };
+    /**
+     * Asks what changing a project between app, lib and package edits: its manifest, the workspace
+     * files and the dependents that name its kind or directory. The host applies the edits and moves
+     * the directory.
+     */
+    'project/kind': {
+        params: ChangeKindParams;
+        result: ChangeKindResult;
+        capability: 'changeKind';
+    };
     /** Asks which version of a project its registry has, so a release can check its tags against it. */
     published: {
         params: PublishedParams;

package/serve/index.d.ts

@@ -1,4 +1,4 @@
 export { serve, serveStreams } from './serve.use-case.ts';
 export { capabilitiesOf, implementsMethod } from './capabilities-of.algorithm.ts';
-export type { Awaitable, Cancellable, CIContributor, Contributor, DeclarationEditor, DependencyManager, Discoverer, DoctorContributor, Generator, LatestReader, Plugin, PluginDescription, Publisher, RegistryReader, Remover, SmithPlugin, Versioner, } from './plugin.contract.ts';
+export type { Awaitable, Cancellable, CIContributor, Contributor, DeclarationEditor, DependencyManager, Discoverer, DoctorContributor, Generator, KindChanger, LatestReader, Plugin, PluginDescription, Publisher, RegistryReader, Remover, SmithPlugin, Versioner, } from './plugin.contract.ts';
 export type { FrameSink, ServeStreams } from './protocol-streams.contract.ts';

package/serve/plugin-members.config.js

@@ -16,6 +16,7 @@ export const PLUGIN_MEMBERS = {
     'doctor': { member: 'doctor', requires: ['doctor'] },
     'contribute': { member: 'contribute', requires: ['contribute'] },
     'remove': { member: 'remove', requires: ['remove'] },
+    'project/kind': { member: 'changeKind', requires: ['changeKind'] },
     'published': { member: 'published', requires: ['published'] },
     'dependencies/install': { member: 'install', requires: ['install', 'uninstall'] },
     'dependencies/uninstall': { member: 'uninstall', requires: ['install', 'uninstall'] },

package/serve/plugin.contract.d.ts

@@ -1,4 +1,4 @@
-import type { CIParams, CIResult, ContributeParams, ContributeResult, DeclaredParams, DeclaredResult, DependencyResult, DiscoverParams, DiscoverResult, DoctorParams, DoctorResult, GenerateParams, GenerateResult, InitializeParams, InitializeResult, InstallParams, LatestParams, LatestResult, PublishedParams, PublishedResult, PublishParams, PublishResult, RemoveParams, RemoveResult, RewriteParams, UninstallParams, VersionParams, VersionResult } from '../protocol/index.ts';
+import type { ChangeKindParams, ChangeKindResult, CIParams, CIResult, ContributeParams, ContributeResult, DeclaredParams, DeclaredResult, DependencyResult, DiscoverParams, DiscoverResult, DoctorParams, DoctorResult, GenerateParams, GenerateResult, InitializeParams, InitializeResult, InstallParams, LatestParams, LatestResult, PublishedParams, PublishedResult, PublishParams, PublishResult, RemoveParams, RemoveResult, RewriteParams, UninstallParams, VersionParams, VersionResult } from '../protocol/index.ts';
 /** A result now or later: every method of a plugin may be `async`. */
 export type Awaitable<T> = T | Promise<T>;
 /** What a plugin says about itself. The serve loop fills in `protocolVersion` and `capabilities`. */
@@ -40,6 +40,10 @@ export interface DoctorContributor {
 export interface Remover {
     remove: (params: RemoveParams, signal: AbortSignal) => Awaitable<RemoveResult>;
 }
+/** `project/kind`: what changing a project between app, lib and package edits. */
+export interface KindChanger {
+    changeKind: (params: ChangeKindParams, signal: AbortSignal) => Awaitable<ChangeKindResult>;
+}
 /** `dependencies/install` and `dependencies/uninstall`: both, or the capability is not advertised. */
 export interface DependencyManager {
     install: (params: InstallParams, signal: AbortSignal) => Awaitable<DependencyResult>;
@@ -77,4 +81,4 @@ export interface Cancellable {
  * from `cancellable`. How many requests it can work on at once is declared in
  * `describe`'s `concurrency`: omit it for one at a time, in order.
  */
-export type SmithPlugin = Plugin & Partial<Discoverer & Generator & Versioner & Publisher & RegistryReader & CIContributor & DoctorContributor & Remover & DependencyManager & DeclarationEditor & LatestReader & Contributor & Cancellable>;
+export type SmithPlugin = Plugin & Partial<Discoverer & Generator & Versioner & Publisher & RegistryReader & CIContributor & DoctorContributor & Remover & KindChanger & DependencyManager & DeclarationEditor & LatestReader & Contributor & Cancellable>;