@monosmith/plugin-sdk 0.4.0 → 0.6.0

package/conformance/check-generation.use-case.js

@@ -21,7 +21,10 @@ function article(kind) {
 export async function checkGeneration(client, workspace, report) {
     const language = effectiveRoles(client.info).includes('language');
     const made = [];
+    const declared = client.info.kinds ?? [];
     for (const kind of ['app', 'lib', 'package']) {
+        if (declared.length > 0 && !declared.includes(kind))
+            continue;
         const name = `c${kind}`;
         const params = {
             kind,

package/package.json

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

@@ -207,6 +207,17 @@ export const protocolSchema = {
             },
             "capability": "latest",
             "notification": false
+        },
+        "sbom/components": {
+            "description": "Asks which components a project ships (its locked dependencies, read from a lockfile where the ecosystem has one and from the manifest otherwise), as package URLs, for the SBOM a release attaches.",
+            "params": {
+                "$ref": "#/$defs/ComponentsParams"
+            },
+            "result": {
+                "$ref": "#/$defs/ComponentsResult"
+            },
+            "capability": "components",
+            "notification": false
         }
     },
     "x-errorCodes": [
@@ -531,6 +542,10 @@ export const protocolSchema = {
                 "cancel": {
                     "type": "boolean",
                     "description": "Cancel says the plugin stops the work of a request when the host sends a cancel notification with its id, then answers that request with its result (if the work was already done) or the request-cancelled error. A host never sends the notification to a plugin without it."
+                },
+                "components": {
+                    "type": "boolean",
+                    "description": "Components lists a project's dependencies for its SBOM."
                 }
             }
         },
@@ -588,6 +603,62 @@ export const protocolSchema = {
                 }
             }
         },
+        "Component": {
+            "description": "Component is one dependency of a project.",
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string"
+                },
+                "version": {
+                    "type": "string",
+                    "description": "Version is the locked version, or the declared range when the project has no lockfile."
+                },
+                "purl": {
+                    "type": "string",
+                    "description": "PURL is the package URL (https://github.com/package-url/purl-spec)."
+                }
+            },
+            "required": [
+                "name",
+                "purl"
+            ]
+        },
+        "ComponentsParams": {
+            "description": "ComponentsParams asks a plugin for the components one of its projects ships: what a CycloneDX SBOM lists.",
+            "type": "object",
+            "properties": {
+                "project": {
+                    "$ref": "#/$defs/Project"
+                }
+            },
+            "required": [
+                "project"
+            ]
+        },
+        "ComponentsResult": {
+            "description": "ComponentsResult lists the components, read from a lockfile where the ecosystem has one and from the manifest otherwise. An empty list is an answer: the project declares no dependencies.",
+            "type": "object",
+            "properties": {
+                "components": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/Component"
+                    }
+                },
+                "source": {
+                    "type": "string",
+                    "description": "Source is the workspace-relative file the list was read from, \"\" when the project has none."
+                },
+                "purl": {
+                    "type": "string",
+                    "description": "PURL is the project's own package URL when it has a registry identity (without a version: the release supplies it); \"\" otherwise."
+                }
+            },
+            "required": [
+                "components"
+            ]
+        },
         "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",
@@ -642,6 +713,10 @@ export const protocolSchema = {
                         }
                     },
                     "description": "DependsOn adds dependencies to tasks the project already has, by task name ({\"lint\": [\"slice-check\"]})."
+                },
+                "release": {
+                    "$ref": "#/$defs/ReleaseDefaults",
+                    "description": "Release is how the project's release files are made, for a project that releases through GitHub releases and leaves them out of its smith.toml [projects.<name>.release] table; what the table sets wins."
                 }
             }
         },
@@ -1163,6 +1238,13 @@ export const protocolSchema = {
                         "$ref": "#/$defs/Stack"
                     },
                     "description": "Stacks are ready-made stacks the plugin publishes."
+                },
+                "kinds": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/ProjectKind"
+                    },
+                    "description": "Kinds are the project kinds the plugin can scaffold with generate. Absent or empty means all three (app, lib and package): what every plugin that says nothing does. A plugin that scaffolds only some, such as an app, lists them, so the host offers and the conformance suite asks for just those."
                 }
             },
             "required": [
@@ -1627,6 +1709,43 @@ export const protocolSchema = {
                 "auth"
             ]
         },
+        "ReleaseDefaults": {
+            "description": "ReleaseDefaults are release settings a plugin supplies for a project: the same fields as the release-from-a-command settings of smith.toml, used for the ones the project's table leaves out.",
+            "type": "object",
+            "properties": {
+                "build": {
+                    "type": "string",
+                    "description": "Build is the shell command that makes the files, run at the workspace root on a runner of each platform."
+                },
+                "assets": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Assets are workspace-relative globs of the files Build leaves."
+                },
+                "platforms": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Platforms are the runner platforms (windows-x64, macos-arm64, macos-x64, linux-x64, linux-arm64)."
+                },
+                "assetName": {
+                    "type": "string",
+                    "description": "AssetName renames each file on upload; see the asset_name setting."
+                },
+                "checksums": {
+                    "type": "boolean",
+                    "description": "Checksums attaches a checksums file for the files a runner uploads."
+                }
+            },
+            "required": [
+                "build",
+                "assets",
+                "platforms"
+            ]
+        },
         "RemoveParams": {
             "description": "RemoveParams tells a plugin a project is being removed. The host deletes the project's directory first; the plugin cleans what it owns outside it (a go.work entry, a lockfile, an installed package).",
             "type": "object",

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

@@ -160,6 +160,8 @@ export interface Capabilities {
      * request-cancelled error. A host never sends the notification to a plugin without it.
      */
     cancel?: boolean;
+    /** Components lists a project's dependencies for its SBOM. */
+    components?: boolean;
 }
 /**
  * ChangeKindParams asks a plugin what changing a project's kind edits. The plugin writes nothing:
@@ -203,6 +205,35 @@ export interface ChangeKindResult {
      */
     warnings?: string[];
 }
+/** Component is one dependency of a project. */
+export interface Component {
+    name: string;
+    /** Version is the locked version, or the declared range when the project has no lockfile. */
+    version?: string;
+    /** PURL is the package URL (https://github.com/package-url/purl-spec). */
+    purl: string;
+}
+/**
+ * ComponentsParams asks a plugin for the components one of its projects ships: what a CycloneDX
+ * SBOM lists.
+ */
+export interface ComponentsParams {
+    project: Project;
+}
+/**
+ * ComponentsResult lists the components, read from a lockfile where the ecosystem has one and from
+ * the manifest otherwise. An empty list is an answer: the project declares no dependencies.
+ */
+export interface ComponentsResult {
+    components: Component[];
+    /** Source is the workspace-relative file the list was read from, "" when the project has none. */
+    source?: string;
+    /**
+     * PURL is the project's own package URL when it has a registry identity (without a version: the
+     * release supplies it); "" otherwise.
+     */
+    purl?: 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
@@ -229,6 +260,12 @@ export interface Contribution {
      * ["slice-check"]}).
      */
     dependsOn?: Record<string, string[]>;
+    /**
+     * Release is how the project's release files are made, for a project that releases through GitHub
+     * releases and leaves them out of its smith.toml [projects.<name>.release] table; what the table
+     * sets wins.
+     */
+    release?: ReleaseDefaults;
 }
 /** Credential is a secret the release phase needs. */
 export interface Credential {
@@ -491,6 +528,13 @@ export interface InitializeResult {
     conflicts?: PluginRef[];
     /** Stacks are ready-made stacks the plugin publishes. */
     stacks?: Stack[];
+    /**
+     * Kinds are the project kinds the plugin can scaffold with generate. Absent or empty means all
+     * three (app, lib and package): what every plugin that says nothing does. A plugin that scaffolds
+     * only some, such as an app, lists them, so the host offers and the conformance suite asks for
+     * just those.
+     */
+    kinds?: ProjectKind[];
 }
 /**
  * Input is one input of an ActionStep. Values are written as quoted YAML strings, except true and
@@ -796,6 +840,28 @@ export interface Registry {
      */
     maven?: string;
 }
+/**
+ * ReleaseDefaults are release settings a plugin supplies for a project: the same fields as the
+ * release-from-a-command settings of smith.toml, used for the ones the project's table leaves out.
+ */
+export interface ReleaseDefaults {
+    /**
+     * Build is the shell command that makes the files, run at the workspace root on a runner of each
+     * platform.
+     */
+    build: string;
+    /** Assets are workspace-relative globs of the files Build leaves. */
+    assets: string[];
+    /**
+     * Platforms are the runner platforms (windows-x64, macos-arm64, macos-x64, linux-x64,
+     * linux-arm64).
+     */
+    platforms: string[];
+    /** AssetName renames each file on upload; see the asset_name setting. */
+    assetName?: string;
+    /** Checksums attaches a checksums file for the files a runner uploads. */
+    checksums?: boolean;
+}
 /**
  * RemoveParams tells a plugin a project is being removed. The host deletes the project's directory
  * first; the plugin cleans what it owns outside it (a go.work entry, a lockfile, an installed
@@ -1121,6 +1187,16 @@ export interface ProtocolMethods {
         result: LatestResult;
         capability: 'latest';
     };
+    /**
+     * Asks which components a project ships (its locked dependencies, read from a lockfile where the
+     * ecosystem has one and from the manifest otherwise), as package URLs, for the SBOM a release
+     * attaches.
+     */
+    'sbom/components': {
+        params: ComponentsParams;
+        result: ComponentsResult;
+        capability: 'components';
+    };
 }
 export type MethodName = keyof ProtocolMethods;
 export type ParamsOf<M extends MethodName> = ProtocolMethods[M]['params'];

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, KindChanger, LatestReader, Plugin, PluginDescription, Publisher, RegistryReader, Remover, SmithPlugin, Versioner, } from './plugin.contract.ts';
+export type { Awaitable, Cancellable, CIContributor, ComponentLister, 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

@@ -23,4 +23,5 @@ export const PLUGIN_MEMBERS = {
     'dependencies/declared': { member: 'declared', requires: ['declared', 'rewrite'] },
     'dependencies/rewrite': { member: 'rewrite', requires: ['declared', 'rewrite'] },
     'dependencies/latest': { member: 'latest', requires: ['latest'] },
+    'sbom/components': { member: 'components', requires: ['components'] },
 };

package/serve/plugin.contract.d.ts

@@ -1,4 +1,4 @@
-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';
+import type { ChangeKindParams, ChangeKindResult, CIParams, CIResult, ComponentsParams, ComponentsResult, 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`. */
@@ -44,6 +44,10 @@ export interface Remover {
 export interface KindChanger {
     changeKind: (params: ChangeKindParams, signal: AbortSignal) => Awaitable<ChangeKindResult>;
 }
+/** `sbom/components`: the components a project ships, for the SBOM a release attaches. */
+export interface ComponentLister {
+    components: (params: ComponentsParams, signal: AbortSignal) => Awaitable<ComponentsResult>;
+}
 /** `dependencies/install` and `dependencies/uninstall`: both, or the capability is not advertised. */
 export interface DependencyManager {
     install: (params: InstallParams, signal: AbortSignal) => Awaitable<DependencyResult>;
@@ -81,4 +85,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 & KindChanger & DependencyManager & DeclarationEditor & LatestReader & Contributor & Cancellable>;
+export type SmithPlugin = Plugin & Partial<Discoverer & Generator & Versioner & Publisher & RegistryReader & CIContributor & DoctorContributor & Remover & KindChanger & ComponentLister & DependencyManager & DeclarationEditor & LatestReader & Contributor & Cancellable>;