@monosmith/plugin-sdk 0.3.0 → 0.5.0

package/conformance/check-generation.use-case.d.ts

@@ -7,6 +7,6 @@ export declare const CONFORMANCE_STACK = "conformance";
  * exist, and, for a language plugin, that its own `discover` returns what it
  * made, with the kind and the stack it was asked for, tasks with commands, and
  * that the dry runs of `version/write`, `remove`, `publish` and `published`
- * answer.
+ * answer, and, for a plugin that changes kinds, what `project/kind` edits.
  */
 export declare function checkGeneration(client: PluginClient, workspace: string, report: ConformanceReport): Promise<void>;

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

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { effectiveRoles } from '../plugin-roles/index.js';
 import { projectKindDirectory } from '../projects/index.js';
+import { checkKindChange } from './check-kind-change.use-case.js';
 import { findManifests } from './find-manifests.algorithm.js';
 import { goList, goQuote } from './go-list.mapper.js';
 /** The stack name generated projects are asked to record. */
@@ -15,12 +16,15 @@ function article(kind) {
  * exist, and, for a language plugin, that its own `discover` returns what it
  * made, with the kind and the stack it was asked for, tasks with commands, and
  * that the dry runs of `version/write`, `remove`, `publish` and `published`
- * answer.
+ * answer, and, for a plugin that changes kinds, what `project/kind` edits.
  */
 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,
@@ -69,6 +73,9 @@ export async function checkGeneration(client, workspace, report) {
         if (client.supports('remove')) {
             await attempt(report, `would remove the ${params.kind} (dry run)`, () => client.call('remove', { project, dryRun: true }, { timeoutMs: 60_000 }));
         }
+        if (client.supports('project/kind')) {
+            await checkKindChange(client, workspace, project, projects, report);
+        }
         if (params.kind === 'package' && client.supports('publish')) {
             await attempt(report, 'publishes the package (dry run)', () => client.call('publish', { project, version: '1.2.3', dryRun: true }, { timeoutMs: 5 * 60_000 }));
         }

package/conformance/check-kind-change.use-case.d.ts

@@ -0,0 +1,9 @@
+import type { PluginClient } from '../host/index.ts';
+import type { Project } from '../protocol/index.ts';
+import type { ConformanceReport } from './conformance-report.model.ts';
+/**
+ * Asks a plugin that declares `changeKind` what making a generated project
+ * another kind edits, and checks it answers with a refusal or with edits to
+ * files that exist, and writes nothing itself: the host applies the edits.
+ */
+export declare function checkKindChange(client: PluginClient, workspace: string, project: Project, all: readonly Project[], report: ConformanceReport): Promise<void>;

package/conformance/check-kind-change.use-case.js

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { projectKindDirectory } from '../projects/index.js';
+import { findManifests } from './find-manifests.algorithm.js';
+import { goList } from './go-list.mapper.js';
+/** The kind a generated project is asked to become: a lib or an app is published as a package, a package goes back to a lib. */
+function kindChangeTarget(kind) {
+    if (kind === 'app')
+        return 'lib';
+    return kind === 'lib' ? 'package' : 'lib';
+}
+function article(kind) {
+    return kind === 'app' ? 'an app' : `a ${kind}`;
+}
+/** The content of every manifest of the workspace, by path. */
+function snapshot(workspace, names) {
+    const content = new Map();
+    for (const manifest of findManifests(workspace, names)) {
+        const text = readFileSync(join(workspace, ...manifest.split('/')), 'utf8');
+        content.set(manifest, text);
+    }
+    return content;
+}
+function same(a, b) {
+    return a.size === b.size && [...a].every(([path, text]) => b.get(path) === text);
+}
+/**
+ * Asks a plugin that declares `changeKind` what making a generated project
+ * another kind edits, and checks it answers with a refusal or with edits to
+ * files that exist, and writes nothing itself: the host applies the edits.
+ */
+export async function checkKindChange(client, workspace, project, all, report) {
+    const to = kindChangeTarget(project.kind);
+    const newRoot = `${projectKindDirectory(to)}/${posix.basename(project.root)}`;
+    const check = `answers what making the ${project.kind} ${article(to)} edits (dry run)`;
+    const names = client.info.manifests ?? [];
+    const before = snapshot(workspace, names);
+    let answer;
+    try {
+        answer = await client.call('project/kind', { project, to, newRoot, projects: [...all] }, { timeoutMs: 5 * 60_000 });
+    }
+    catch (error) {
+        report.add(check, false, error instanceof Error ? error.message : String(error));
+        return;
+    }
+    const files = answer.files ?? [];
+    const missing = files.map(file => file.path).filter(path => !existsSync(join(workspace, ...path.split('/'))));
+    if ((answer.refused ?? '') === '' && files.length === 0) {
+        report.add(check, false, 'it answered with neither a refusal nor an edit: a changed kind is recorded in a file');
+    }
+    else if (missing.length > 0) {
+        report.add(check, false, `edits files that do not exist (paths are those before the move): ${goList(missing)}`);
+    }
+    else {
+        const untouched = same(before, snapshot(workspace, names));
+        report.add(check, untouched, 'it wrote to the workspace: it must only answer with the new content, and let the host write it');
+    }
+}

package/package.json

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

@@ -642,6 +642,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 +1167,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 +1638,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

@@ -229,6 +229,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 +497,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 +809,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