@monosmith/plugin-sdk 0.2.1 → 0.4.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,7 +16,7 @@ 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');
@@ -69,6 +70,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.2.1",
+  "version": "0.4.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",
@@ -1341,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
@@ -611,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.
@@ -1019,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>;