@monosmith/plugin-sdk 0.6.0 → 2.0.0-beta.2

package/package.json

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

@@ -218,6 +218,28 @@ export const protocolSchema = {
             },
             "capability": "components",
             "notification": false
+        },
+        "derive": {
+            "description": "Asks which files a plugin derives from facts and the project graph (a tsconfig's references, a test config's display name). The plugin writes nothing: it answers with the content, and the host rewrites a file only when its ownership record allows.",
+            "params": {
+                "$ref": "#/$defs/DeriveParams"
+            },
+            "result": {
+                "$ref": "#/$defs/DeriveResult"
+            },
+            "capability": "derive",
+            "notification": false
+        },
+        "api/surface": {
+            "description": "Asks for the public API names of a project, at the working tree or at a git revision (its last release tag), so a release can compare them and say what bump the change needs.",
+            "params": {
+                "$ref": "#/$defs/APISurfaceParams"
+            },
+            "result": {
+                "$ref": "#/$defs/APISurfaceResult"
+            },
+            "capability": "apiSurface",
+            "notification": false
         }
     },
     "x-errorCodes": [
@@ -298,6 +320,42 @@ export const protocolSchema = {
         }
     ],
     "$defs": {
+        "APISurfaceParams": {
+            "description": "APISurfaceParams asks a plugin for the public API names of one project.",
+            "type": "object",
+            "properties": {
+                "project": {
+                    "$ref": "#/$defs/Project"
+                },
+                "ref": {
+                    "type": "string",
+                    "description": "Ref is the git revision to read the project at (the tag of its last release). Empty means the working tree."
+                }
+            },
+            "required": [
+                "project"
+            ]
+        },
+        "APISurfaceResult": {
+            "description": "APISurfaceResult is the public API of a project: the names its entry points export. A host compares the names of two revisions; it never reads their meaning, so a plugin chooses its own spelling and keeps it stable.",
+            "type": "object",
+            "properties": {
+                "names": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Names are the exported names, sorted. A name an entry point other than the main one exports is prefixed with that entry point and a colon (\"./cli:run\"). An empty list is an answer: the project exports nothing."
+                },
+                "unreadable": {
+                    "type": "string",
+                    "description": "Unreadable says why the API could not be listed (no entry point, no source at the revision). When set, Names is empty and the host skips the project without a warning."
+                }
+            },
+            "required": [
+                "names"
+            ]
+        },
         "ActionStep": {
             "description": "ActionStep is a provider-native step: a GitHub action or an Azure task, with its inputs in the order they are written.",
             "type": "object",
@@ -546,6 +604,18 @@ export const protocolSchema = {
                 "components": {
                     "type": "boolean",
                     "description": "Components lists a project's dependencies for its SBOM."
+                },
+                "derive": {
+                    "type": "boolean",
+                    "description": "Derive says which files the plugin derives from facts and the project graph (smith derive)."
+                },
+                "apiSurface": {
+                    "type": "boolean",
+                    "description": "APISurface lists the names a project exports, at a git revision, so a release can warn when the commits ask for a smaller bump than the API change needs."
+                },
+                "channels": {
+                    "type": "boolean",
+                    "description": "Channels says a prerelease version the plugin publishes never takes the place of the stable one: the plugin publishes under PublishParams.Tag, a release channel's name, without moving the registry's stable pointer (npm's latest), or its registry orders a prerelease below the release (PyPI, NuGet) and needs no tag. A host does not publish a package of a release channel with a plugin that lacks it."
                 }
             }
         },
@@ -603,6 +673,68 @@ export const protocolSchema = {
                 }
             }
         },
+        "Choice": {
+            "description": "Choice is one option on an axis of a project's make-up: a framework, a test runner, a style library. A plugin publishes the choices it owns in InitializeResult.Choices; the host checks a selection of them (smith add --with react,vitest,bootstrap) and turns it into a stack. What a choice writes (dependencies, tasks, files) stays with the plugin: the host never sees it.",
+            "type": "object",
+            "properties": {
+                "axis": {
+                    "type": "string",
+                    "description": "Axis is the question the choice answers: \"framework\", \"test\", \"style\", \"lint\". The plugins agree on the name; the host only compares it."
+                },
+                "name": {
+                    "type": "string",
+                    "description": "Name identifies the choice in a selection and is unique among the choices of all loaded plugins."
+                },
+                "description": {
+                    "type": "string"
+                },
+                "language": {
+                    "type": "string",
+                    "description": "Language is the language plugin the choice applies to (\"node\")."
+                },
+                "roles": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/Role"
+                    },
+                    "description": "Roles are the roles the choice's plugin plays in a stack built from it: scaffold (it writes the project) and/or toolchain (it joins the toolchain). Empty means it only adds to what a plugin of the selection already writes, as a style does."
+                },
+                "needs": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Needs are axes that the selection must have a choice on. An axis the person leaves out is filled with the default of the axis."
+                },
+                "default": {
+                    "type": "boolean",
+                    "description": "Default marks the choice the host adds when a selection needs its axis and has no choice on it."
+                },
+                "many": {
+                    "type": "boolean",
+                    "description": "Many allows the choice next to other choices of its axis that are Many too. By default a selection has one choice per axis."
+                },
+                "requires": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Requires are choices that must be in the selection."
+                },
+                "conflicts": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Conflicts are choices that must not be in the selection."
+                }
+            },
+            "required": [
+                "axis",
+                "name",
+                "language"
+            ]
+        },
         "Component": {
             "description": "Component is one dependency of a project.",
             "type": "object",
@@ -717,6 +849,10 @@ export const protocolSchema = {
                 "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."
+                },
+                "facts": {
+                    "type": "object",
+                    "description": "Facts are the plugin's default facts for the project: typed values under namespaced keys ({\"source.roots\": [\"src\"]}) that other settings and plugins read through the merged Project.Facts. They are the lowest scope: a [facts] table in smith.toml wins over them, and two plugins that publish different values for one key are an error that names both."
                 }
             }
         },
@@ -805,6 +941,28 @@ export const protocolSchema = {
                 "projects"
             ]
         },
+        "DeclaredProject": {
+            "description": "DeclaredProject is a project smith.toml declares: a folder with no manifest.",
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Name is the project's name, the key of its [projects.<name>] table."
+                },
+                "root": {
+                    "type": "string",
+                    "description": "Root is the workspace-relative folder."
+                },
+                "kind": {
+                    "$ref": "#/$defs/ProjectKind",
+                    "description": "Kind is \"app\", \"lib\" or \"package\", or empty for the plugin's choice."
+                }
+            },
+            "required": [
+                "name",
+                "root"
+            ]
+        },
         "DeclaredResult": {
             "description": "DeclaredResult is every declaration, and the version installed of each name where the plugin can tell.",
             "type": "object",
@@ -844,6 +1002,114 @@ export const protocolSchema = {
                 }
             }
         },
+        "DeriveParams": {
+            "description": "DeriveParams asks a plugin for the files it can derive from facts and the project graph. The plugin writes nothing: it answers with the content, and the host decides, from its ownership record, whether to write it.",
+            "type": "object",
+            "properties": {
+                "projects": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/Project"
+                    },
+                    "description": "Projects are the projects the plugin serves."
+                },
+                "graph": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "description": "Graph maps a project name to the names of the projects it depends on inside the workspace, sorted. The host resolved these edges: a plugin does not repeat that work."
+                },
+                "owned": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Owned are the workspace-relative paths the host's ownership record says smith owns. A plugin proposes such a file again even when it is missing on disk, so deleting a derived file and deriving restores it. A file that is not owned and not on disk is not proposed."
+                }
+            },
+            "required": [
+                "projects"
+            ]
+        },
+        "DeriveResult": {
+            "description": "DeriveResult carries the files a plugin derives.",
+            "type": "object",
+            "properties": {
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/DerivedFile"
+                    }
+                },
+                "diverging": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/DivergentFile"
+                    },
+                    "description": "Diverging are files a renderer looked at and left alone because they differ from the shape their siblings share. They are not drift: the project owns them. The host shows them in `smith derive --explain` and in the doctor, and never writes them."
+                }
+            },
+            "required": [
+                "files"
+            ]
+        },
+        "DerivedFile": {
+            "description": "DerivedFile is the content one renderer derives for one file.",
+            "type": "object",
+            "properties": {
+                "project": {
+                    "type": "string",
+                    "description": "Project is the project the file belongs to."
+                },
+                "path": {
+                    "type": "string",
+                    "description": "Path is workspace-relative, with forward slashes."
+                },
+                "mode": {
+                    "type": "string",
+                    "description": "Mode is DeriveFile, DeriveRegion or DeriveKeys."
+                },
+                "renderer": {
+                    "type": "string",
+                    "description": "Renderer is the stable id of the renderer, for example \"node.tsconfig.references\". It names the region markers."
+                },
+                "version": {
+                    "type": "integer",
+                    "description": "Version is the renderer's version. A new version means new output for the same inputs, so the host rewrites an unedited file."
+                },
+                "content": {
+                    "type": "string",
+                    "description": "Content is the whole file (DeriveFile) or the lines of the region (DeriveRegion), without the markers. Unused for DeriveKeys."
+                },
+                "comment": {
+                    "type": "string",
+                    "description": "Comment is the line comment leader of the file (\"//\", \"#\"): the host writes a generated header after it in a DeriveFile. Empty for a format without comments, then the file has no header."
+                },
+                "format": {
+                    "type": "string",
+                    "description": "Format is \"json\" or \"toml\" for DeriveKeys."
+                },
+                "table": {
+                    "type": "string",
+                    "description": "Table is the TOML table that holds the keys (\"tool.smith\"); required for \"toml\", unused for \"json\", whose keys are the top-level ones."
+                },
+                "keys": {
+                    "type": "object",
+                    "description": "Keys are the owned keys and their values (DeriveKeys). A TOML value is a string, a number, a boolean or an array of those."
+                }
+            },
+            "required": [
+                "project",
+                "path",
+                "mode",
+                "renderer",
+                "version"
+            ]
+        },
         "DevcontainerFeature": {
             "description": "DevcontainerFeature is a dev container feature and its options (https://containers.dev/features).",
             "type": "object",
@@ -872,6 +1138,13 @@ export const protocolSchema = {
                     "items": {
                         "type": "string"
                     }
+                },
+                "declared": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/DeclaredProject"
+                    },
+                    "description": "Declared are the projects smith.toml declares for this plugin's language ([projects.<name>] with a root and a language): folders with no manifest of their own, such as a program that is a package of the Go module above it. The plugin describes each one in its result, or answers with an error saying why it cannot."
                 }
             },
             "required": [
@@ -893,6 +1166,34 @@ export const protocolSchema = {
                 "projects"
             ]
         },
+        "DivergentFile": {
+            "description": "DivergentFile is a file a renderer does not derive because the project made it differ from its siblings.",
+            "type": "object",
+            "properties": {
+                "project": {
+                    "type": "string",
+                    "description": "Project is the project the file belongs to."
+                },
+                "path": {
+                    "type": "string",
+                    "description": "Path is workspace-relative, with forward slashes."
+                },
+                "renderer": {
+                    "type": "string",
+                    "description": "Renderer is the stable id of the renderer that compared the file."
+                },
+                "detail": {
+                    "type": "string",
+                    "description": "Detail says in a sentence how the file differs from its siblings."
+                }
+            },
+            "required": [
+                "project",
+                "path",
+                "renderer",
+                "detail"
+            ]
+        },
         "DoctorParams": {
             "description": "DoctorParams gives the plugin its projects to check.",
             "type": "object",
@@ -1109,6 +1410,24 @@ export const protocolSchema = {
                 "settings": {
                     "type": "object",
                     "description": "Settings are this plugin's own settings for the new project, from the recipe the project is created from (its settings.<plugin> table); the same table is later the plugin's entry in Project.Settings. Nil when there are none."
+                },
+                "facts": {
+                    "type": "object",
+                    "description": "Facts are the shared facts that hold for the new project, from smith.toml: [projects.<name>.facts] over [facts]. A key that is absent was set by no one: the plugin scaffolds its own default. Set by the host; read only."
+                },
+                "shape": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    },
+                    "description": "Shape is the dialect the new project should have: the facts (see Project.Shape) that most projects of its kind and language agree on, as the host counted them. A plugin applies the keys it follows (see InitializeResult.Follows) and ignores the rest. Nil when there is nothing to follow, or the person asked for a fresh project."
+                },
+                "choices": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Choices are the choices (see Choice) the new project is built from, the stack's Choices, in the order they apply: a choice comes after those it requires. A plugin applies the choices it owns and ignores the rest. Absent when the stack is not a selection. Set by the host; read only."
                 }
             },
             "required": [
@@ -1245,6 +1564,20 @@ export const protocolSchema = {
                         "$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."
+                },
+                "follows": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Follows are the shape keys (see Project.Shape) the plugin applies when it generates a project with GenerateParams.Shape. Where siblings split on a key, the host asks the person only for a key that a plugin of the stack follows. Absent means the plugin follows none."
+                },
+                "choices": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/Choice"
+                    },
+                    "description": "Choices are the options on an axis (framework, test, style) the plugin owns. The host lists them (smith choices) and checks a selection of them (smith add --with). Absent means the plugin owns none."
                 }
             },
             "required": [
@@ -1489,6 +1822,13 @@ export const protocolSchema = {
                     },
                     "description": "Settings are plugins' settings for this project from smith.toml, by plugin name: [projects.<project>.settings.<name>] (what a recipe's settings became when it created the project), and for a convention its [conventions.<name>] settings and the project's [projects.<project>.<name>] on top. Set by the host; a plugin reads its own entry."
                 },
+                "shape": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    },
+                    "description": "Shape is the dialect of the project: named facts about how it is made (\"build.tool\": \"esbuild\", \"test.runner\": \"@swc/jest\", \"exports.target\": \"dist\"), each a short string, read from the manifest and files the plugin already reads in discovery. The host counts the shapes of the projects of one kind and language to let a new project follow what they do, and knows no key itself. Nil when the plugin does not describe shapes."
+                },
                 "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."
@@ -1496,6 +1836,10 @@ export const protocolSchema = {
                 "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."
+                },
+                "facts": {
+                    "type": "object",
+                    "description": "Facts are the shared facts that hold for the project, merged by the host, narrowest scope first: [projects.<name>.facts], then [facts], then the defaults plugins published through Contribution.Facts. A key that is absent was set by no one: the plugin uses its own default. A request made before every plugin has contributed carries the smith.toml facts and the defaults published so far. Set by the host; read only."
                 }
             },
             "required": [
@@ -1545,6 +1889,10 @@ export const protocolSchema = {
                 },
                 "branch": {
                     "type": "string"
+                },
+                "tag": {
+                    "type": "string",
+                    "description": "Tag is the name of the release channel the version belongs to (npm's dist-tag \"beta\"). When set, the plugin publishes under it and leaves the registry's stable pointer where it is, or ignores it when its registry has no such pointer. Only sent to a plugin with the channels capability."
                 }
             },
             "required": [
@@ -1924,6 +2272,13 @@ export const protocolSchema = {
                     "items": {
                         "type": "string"
                     }
+                },
+                "choices": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Choices make the stack a saved selection (see Choice). When they are set, the host derives the language, the scaffold and the toolchain from them, and Toolchain lists only the plugins to add after those. The plugins of the stack get the choices in GenerateParams.Choices."
                 }
             },
             "required": [

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

@@ -38,6 +38,33 @@ export declare const ERROR_CODES: {
     readonly RequestCancelled: -32800;
 };
 export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/** APISurfaceParams asks a plugin for the public API names of one project. */
+export interface APISurfaceParams {
+    project: Project;
+    /**
+     * Ref is the git revision to read the project at (the tag of its last release). Empty means the
+     * working tree.
+     */
+    ref?: string;
+}
+/**
+ * APISurfaceResult is the public API of a project: the names its entry points export. A host
+ * compares the names of two revisions; it never reads their meaning, so a plugin chooses its own
+ * spelling and keeps it stable.
+ */
+export interface APISurfaceResult {
+    /**
+     * Names are the exported names, sorted. A name an entry point other than the main one exports is
+     * prefixed with that entry point and a colon ("./cli:run"). An empty list is an answer: the
+     * project exports nothing.
+     */
+    names: string[];
+    /**
+     * Unreadable says why the API could not be listed (no entry point, no source at the revision).
+     * When set, Names is empty and the host skips the project without a warning.
+     */
+    unreadable?: string;
+}
 /**
  * ActionStep is a provider-native step: a GitHub action or an Azure task, with its inputs in the
  * order they are written.
@@ -162,6 +189,21 @@ export interface Capabilities {
     cancel?: boolean;
     /** Components lists a project's dependencies for its SBOM. */
     components?: boolean;
+    /** Derive says which files the plugin derives from facts and the project graph (smith derive). */
+    derive?: boolean;
+    /**
+     * APISurface lists the names a project exports, at a git revision, so a release can warn when the
+     * commits ask for a smaller bump than the API change needs.
+     */
+    apiSurface?: boolean;
+    /**
+     * Channels says a prerelease version the plugin publishes never takes the place of the stable
+     * one: the plugin publishes under PublishParams.Tag, a release channel's name, without moving the
+     * registry's stable pointer (npm's latest), or its registry orders a prerelease below the release
+     * (PyPI, NuGet) and needs no tag. A host does not publish a package of a release channel with a
+     * plugin that lacks it.
+     */
+    channels?: boolean;
 }
 /**
  * ChangeKindParams asks a plugin what changing a project's kind edits. The plugin writes nothing:
@@ -205,6 +247,49 @@ export interface ChangeKindResult {
      */
     warnings?: string[];
 }
+/**
+ * Choice is one option on an axis of a project's make-up: a framework, a test runner, a style
+ * library. A plugin publishes the choices it owns in InitializeResult.Choices; the host checks a
+ * selection of them (smith add --with react,vitest,bootstrap) and turns it into a stack. What a
+ * choice writes (dependencies, tasks, files) stays with the plugin: the host never sees it.
+ */
+export interface Choice {
+    /**
+     * Axis is the question the choice answers: "framework", "test", "style", "lint". The plugins
+     * agree on the name; the host only compares it.
+     */
+    axis: string;
+    /**
+     * Name identifies the choice in a selection and is unique among the choices of all loaded
+     * plugins.
+     */
+    name: string;
+    description?: string;
+    /** Language is the language plugin the choice applies to ("node"). */
+    language: string;
+    /**
+     * Roles are the roles the choice's plugin plays in a stack built from it: scaffold (it writes the
+     * project) and/or toolchain (it joins the toolchain). Empty means it only adds to what a plugin
+     * of the selection already writes, as a style does.
+     */
+    roles?: Role[];
+    /**
+     * Needs are axes that the selection must have a choice on. An axis the person leaves out is
+     * filled with the default of the axis.
+     */
+    needs?: string[];
+    /** Default marks the choice the host adds when a selection needs its axis and has no choice on it. */
+    default?: boolean;
+    /**
+     * Many allows the choice next to other choices of its axis that are Many too. By default a
+     * selection has one choice per axis.
+     */
+    many?: boolean;
+    /** Requires are choices that must be in the selection. */
+    requires?: string[];
+    /** Conflicts are choices that must not be in the selection. */
+    conflicts?: string[];
+}
 /** Component is one dependency of a project. */
 export interface Component {
     name: string;
@@ -266,6 +351,13 @@ export interface Contribution {
      * sets wins.
      */
     release?: ReleaseDefaults;
+    /**
+     * Facts are the plugin's default facts for the project: typed values under namespaced keys
+     * ({"source.roots": ["src"]}) that other settings and plugins read through the merged
+     * Project.Facts. They are the lowest scope: a [facts] table in smith.toml wins over them, and two
+     * plugins that publish different values for one key are an error that names both.
+     */
+    facts?: Record<string, unknown>;
 }
 /** Credential is a secret the release phase needs. */
 export interface Credential {
@@ -314,6 +406,15 @@ export interface Declaration {
 export interface DeclaredParams {
     projects: Project[];
 }
+/** DeclaredProject is a project smith.toml declares: a folder with no manifest. */
+export interface DeclaredProject {
+    /** Name is the project's name, the key of its [projects.<name>] table. */
+    name: string;
+    /** Root is the workspace-relative folder. */
+    root: string;
+    /** Kind is "app", "lib" or "package", or empty for the plugin's choice. */
+    kind?: ProjectKind;
+}
 /**
  * DeclaredResult is every declaration, and the version installed of each name where the plugin can
  * tell.
@@ -327,6 +428,77 @@ export interface DependencyResult {
     files?: string[];
     notes?: string[];
 }
+/**
+ * DeriveParams asks a plugin for the files it can derive from facts and the project graph. The
+ * plugin writes nothing: it answers with the content, and the host decides, from its ownership
+ * record, whether to write it.
+ */
+export interface DeriveParams {
+    /** Projects are the projects the plugin serves. */
+    projects: Project[];
+    /**
+     * Graph maps a project name to the names of the projects it depends on inside the workspace,
+     * sorted. The host resolved these edges: a plugin does not repeat that work.
+     */
+    graph?: Record<string, string[]>;
+    /**
+     * Owned are the workspace-relative paths the host's ownership record says smith owns. A plugin
+     * proposes such a file again even when it is missing on disk, so deleting a derived file and
+     * deriving restores it. A file that is not owned and not on disk is not proposed.
+     */
+    owned?: string[];
+}
+/** DeriveResult carries the files a plugin derives. */
+export interface DeriveResult {
+    files: DerivedFile[];
+    /**
+     * Diverging are files a renderer looked at and left alone because they differ from the shape
+     * their siblings share. They are not drift: the project owns them. The host shows them in `smith
+     * derive --explain` and in the doctor, and never writes them.
+     */
+    diverging?: DivergentFile[];
+}
+/** DerivedFile is the content one renderer derives for one file. */
+export interface DerivedFile {
+    /** Project is the project the file belongs to. */
+    project: string;
+    /** Path is workspace-relative, with forward slashes. */
+    path: string;
+    /** Mode is DeriveFile, DeriveRegion or DeriveKeys. */
+    mode: string;
+    /**
+     * Renderer is the stable id of the renderer, for example "node.tsconfig.references". It names the
+     * region markers.
+     */
+    renderer: string;
+    /**
+     * Version is the renderer's version. A new version means new output for the same inputs, so the
+     * host rewrites an unedited file.
+     */
+    version: number;
+    /**
+     * Content is the whole file (DeriveFile) or the lines of the region (DeriveRegion), without the
+     * markers. Unused for DeriveKeys.
+     */
+    content?: string;
+    /**
+     * Comment is the line comment leader of the file ("//", "#"): the host writes a generated header
+     * after it in a DeriveFile. Empty for a format without comments, then the file has no header.
+     */
+    comment?: string;
+    /** Format is "json" or "toml" for DeriveKeys. */
+    format?: string;
+    /**
+     * Table is the TOML table that holds the keys ("tool.smith"); required for "toml", unused for
+     * "json", whose keys are the top-level ones.
+     */
+    table?: string;
+    /**
+     * Keys are the owned keys and their values (DeriveKeys). A TOML value is a string, a number, a
+     * boolean or an array of those.
+     */
+    keys?: Record<string, unknown>;
+}
 /** DevcontainerFeature is a dev container feature and its options (https://containers.dev/features). */
 export interface DevcontainerFeature {
     /** ID is the feature reference, e.g. "ghcr.io/devcontainers/features/go:1". */
@@ -339,6 +511,13 @@ export interface DevcontainerFeature {
  */
 export interface DiscoverParams {
     manifests: string[];
+    /**
+     * Declared are the projects smith.toml declares for this plugin's language ([projects.<name>]
+     * with a root and a language): folders with no manifest of their own, such as a program that is a
+     * package of the Go module above it. The plugin describes each one in its result, or answers with
+     * an error saying why it cannot.
+     */
+    declared?: DeclaredProject[];
 }
 /**
  * DiscoverResult describes every manifest that is a project of this plugin. A manifest the plugin
@@ -347,6 +526,20 @@ export interface DiscoverParams {
 export interface DiscoverResult {
     projects: Project[];
 }
+/**
+ * DivergentFile is a file a renderer does not derive because the project made it differ from its
+ * siblings.
+ */
+export interface DivergentFile {
+    /** Project is the project the file belongs to. */
+    project: string;
+    /** Path is workspace-relative, with forward slashes. */
+    path: string;
+    /** Renderer is the stable id of the renderer that compared the file. */
+    renderer: string;
+    /** Detail says in a sentence how the file differs from its siblings. */
+    detail: string;
+}
 /** DoctorParams gives the plugin its projects to check. */
 export interface DoctorParams {
     projects: Project[];
@@ -464,6 +657,25 @@ export interface GenerateParams {
      * Project.Settings. Nil when there are none.
      */
     settings?: Record<string, unknown>;
+    /**
+     * Facts are the shared facts that hold for the new project, from smith.toml:
+     * [projects.<name>.facts] over [facts]. A key that is absent was set by no one: the plugin
+     * scaffolds its own default. Set by the host; read only.
+     */
+    facts?: Record<string, unknown>;
+    /**
+     * Shape is the dialect the new project should have: the facts (see Project.Shape) that most
+     * projects of its kind and language agree on, as the host counted them. A plugin applies the keys
+     * it follows (see InitializeResult.Follows) and ignores the rest. Nil when there is nothing to
+     * follow, or the person asked for a fresh project.
+     */
+    shape?: Record<string, string>;
+    /**
+     * Choices are the choices (see Choice) the new project is built from, the stack's Choices, in the
+     * order they apply: a choice comes after those it requires. A plugin applies the choices it owns
+     * and ignores the rest. Absent when the stack is not a selection. Set by the host; read only.
+     */
+    choices?: string[];
 }
 /** GenerateResult lists what the plugin wrote, workspace-relative. */
 export interface GenerateResult {
@@ -535,6 +747,18 @@ export interface InitializeResult {
      * just those.
      */
     kinds?: ProjectKind[];
+    /**
+     * Follows are the shape keys (see Project.Shape) the plugin applies when it generates a project
+     * with GenerateParams.Shape. Where siblings split on a key, the host asks the person only for a
+     * key that a plugin of the stack follows. Absent means the plugin follows none.
+     */
+    follows?: string[];
+    /**
+     * Choices are the options on an axis (framework, test, style) the plugin owns. The host lists
+     * them (smith choices) and checks a selection of them (smith add --with). Absent means the plugin
+     * owns none.
+     */
+    choices?: Choice[];
 }
 /**
  * Input is one input of an ActionStep. Values are written as quoted YAML strings, except true and
@@ -694,6 +918,14 @@ export interface Project {
      * [projects.<project>.<name>] on top. Set by the host; a plugin reads its own entry.
      */
     settings?: Record<string, Record<string, unknown>>;
+    /**
+     * Shape is the dialect of the project: named facts about how it is made ("build.tool": "esbuild",
+     * "test.runner": "@swc/jest", "exports.target": "dist"), each a short string, read from the
+     * manifest and files the plugin already reads in discovery. The host counts the shapes of the
+     * projects of one kind and language to let a new project follow what they do, and knows no key
+     * itself. Nil when the plugin does not describe shapes.
+     */
+    shape?: Record<string, string>;
     /**
      * 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.
@@ -705,6 +937,14 @@ export interface Project {
      * a project that has no release files. Set by the host.
      */
     releaseAssets?: AssetSpec;
+    /**
+     * Facts are the shared facts that hold for the project, merged by the host, narrowest scope
+     * first: [projects.<name>.facts], then [facts], then the defaults plugins published through
+     * Contribution.Facts. A key that is absent was set by no one: the plugin uses its own default. A
+     * request made before every plugin has contributed carries the smith.toml facts and the defaults
+     * published so far. Set by the host; read only.
+     */
+    facts?: Record<string, unknown>;
 }
 /**
  * ProjectKind is the universal kind vocabulary.
@@ -742,6 +982,13 @@ export interface PublishParams {
      */
     commit?: string;
     branch?: string;
+    /**
+     * Tag is the name of the release channel the version belongs to (npm's dist-tag "beta"). When
+     * set, the plugin publishes under it and leaves the registry's stable pointer where it is, or
+     * ignores it when its registry has no such pointer. Only sent to a plugin with the channels
+     * capability.
+     */
+    tag?: string;
 }
 /**
  * PublishResult reports what happened. Skipped with a reason is a success: an already-published
@@ -931,6 +1178,12 @@ export interface Stack {
     /** Scaffold generates new projects; empty means the language plugin does. */
     scaffold?: string;
     deploy?: string[];
+    /**
+     * Choices make the stack a saved selection (see Choice). When they are set, the host derives the
+     * language, the scaffold and the toolchain from them, and Toolchain lists only the plugins to add
+     * after those. The plugins of the stack get the choices in GenerateParams.Choices.
+     */
+    choices?: string[];
 }
 /** Step is one command a CI phase runs. */
 export interface Step {
@@ -1197,6 +1450,25 @@ export interface ProtocolMethods {
         result: ComponentsResult;
         capability: 'components';
     };
+    /**
+     * Asks which files a plugin derives from facts and the project graph (a tsconfig's references, a
+     * test config's display name). The plugin writes nothing: it answers with the content, and the
+     * host rewrites a file only when its ownership record allows.
+     */
+    derive: {
+        params: DeriveParams;
+        result: DeriveResult;
+        capability: 'derive';
+    };
+    /**
+     * Asks for the public API names of a project, at the working tree or at a git revision (its last
+     * release tag), so a release can compare them and say what bump the change needs.
+     */
+    'api/surface': {
+        params: APISurfaceParams;
+        result: APISurfaceResult;
+        capability: 'apiSurface';
+    };
 }
 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, ComponentLister, Contributor, DeclarationEditor, DependencyManager, Discoverer, DoctorContributor, Generator, KindChanger, LatestReader, Plugin, PluginDescription, Publisher, RegistryReader, Remover, SmithPlugin, Versioner, } from './plugin.contract.ts';
+export type { APISurfaceReader, Awaitable, Cancellable, CIContributor, ComponentLister, Contributor, DeclarationEditor, DependencyManager, Deriver, 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

@@ -24,4 +24,6 @@ export const PLUGIN_MEMBERS = {
     'dependencies/rewrite': { member: 'rewrite', requires: ['declared', 'rewrite'] },
     'dependencies/latest': { member: 'latest', requires: ['latest'] },
     'sbom/components': { member: 'components', requires: ['components'] },
+    'derive': { member: 'derive', requires: ['derive'] },
+    'api/surface': { member: 'apiSurface', requires: ['apiSurface'] },
 };

package/serve/plugin.contract.d.ts

@@ -1,4 +1,4 @@
-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';
+import type { DeriveParams, DeriveResult, APISurfaceParams, APISurfaceResult, 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`. */
@@ -48,6 +48,14 @@ export interface KindChanger {
 export interface ComponentLister {
     components: (params: ComponentsParams, signal: AbortSignal) => Awaitable<ComponentsResult>;
 }
+/** `derive`: the files the plugin derives from facts and the project graph (smith derive). */
+export interface Deriver {
+    derive: (params: DeriveParams, signal: AbortSignal) => Awaitable<DeriveResult>;
+}
+/** `api/surface`: the public API names of a project at a git revision, for the release's version check. */
+export interface APISurfaceReader {
+    apiSurface: (params: APISurfaceParams, signal: AbortSignal) => Awaitable<APISurfaceResult>;
+}
 /** `dependencies/install` and `dependencies/uninstall`: both, or the capability is not advertised. */
 export interface DependencyManager {
     install: (params: InstallParams, signal: AbortSignal) => Awaitable<DependencyResult>;
@@ -85,4 +93,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 & ComponentLister & DependencyManager & DeclarationEditor & LatestReader & Contributor & Cancellable>;
+export type SmithPlugin = Plugin & Partial<Discoverer & Generator & Versioner & Publisher & RegistryReader & CIContributor & DoctorContributor & Remover & KindChanger & ComponentLister & Deriver & APISurfaceReader & DependencyManager & DeclarationEditor & LatestReader & Contributor & Cancellable>;