@monosmith/plugin-sdk 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,1057 @@
+/** The protocol major version this SDK speaks. A breaking change to the protocol raises it. */
+export declare const PROTOCOL_VERSION = 1;
+/** The largest message the framing accepts, in bytes. */
+export declare const MAX_MESSAGE_BYTES = 67108864;
+/** The error codes of the protocol: the JSON-RPC 2.0 ones, and `PluginFailure` for a failure the user must act on. */
+export declare const ERROR_CODES: {
+    /** The message was not valid JSON. The response has a null id. */
+    readonly ParseError: -32700;
+    /**
+     * The request is not valid, or arrived out of order: every request before initialize is refused
+     * with this code.
+     */
+    readonly InvalidRequest: -32600;
+    /**
+     * The plugin does not implement the method, or did not advertise the capability. The message is
+     * "method not supported: <method>".
+     */
+    readonly MethodNotFound: -32601;
+    /** The params do not have the shape the method expects. */
+    readonly InvalidParams: -32602;
+    /**
+     * The plugin failed in a way that is not the user's to act on, for example a result that could
+     * not be encoded.
+     */
+    readonly InternalError: -32603;
+    /**
+     * The method ran and failed for a reason the user must act on (a missing toolchain, a bad
+     * manifest). The message is shown to the user as it is, so it should say what to do. An error a
+     * method of the Go SDK returns becomes this code.
+     */
+    readonly PluginFailure: -32000;
+    /**
+     * The plugin stopped the request because the host sent a cancel notification for its id. A plugin
+     * that had finished answers with the result instead. Only a plugin that advertised the cancel
+     * capability sends it; when a cancelled request fails with any error, the SDKs answer with this
+     * code.
+     */
+    readonly RequestCancelled: -32800;
+};
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/**
+ * ActionStep is a provider-native step: a GitHub action or an Azure task, with its inputs in the
+ * order they are written.
+ */
+export interface ActionStep {
+    /** Uses is the action ("actions/setup-go@v7") or task ("GoTool@0"). */
+    uses: string;
+    inputs?: Input[];
+}
+/** AssetSpec describes the release files of an app. */
+export interface AssetSpec {
+    /** Name is the file name pattern; placeholders are {product}, {version}, {os}, {arch} and {ext}. */
+    name: string;
+    /** Product fills {product}; it defaults to the project name. */
+    product?: string;
+    /** Platforms are "os/arch" pairs in the language's own spelling. */
+    platforms: string[];
+    /** OSAlias and ArchAlias rename an os or arch in file names only. */
+    osAlias?: Record<string, string>;
+    archAlias?: Record<string, string>;
+    /**
+     * VersionVariable is the symbol the version is stamped into, for languages that stamp at link
+     * time (Go: main.version).
+     */
+    versionVariable?: string;
+    /** OutDir is the workspace-relative directory the files go to. */
+    outDir: string;
+}
+/** AuditSettings are the workspace's audit policy choices ([ci] audit_*). */
+export interface AuditSettings {
+    /**
+     * Policies are the ecosystems ("node", "go", "python", "rust") whose policy checks run in `smith
+     * ci audit`, as extra Audit steps.
+     */
+    policies?: string[];
+    /** Warn are the policies whose checks only warn instead of blocking. */
+    warn?: string[];
+    /** AllowInstallScripts names npm packages whose install scripts the node policy accepts. */
+    allowInstallScripts?: string[];
+    /** MaxUnsafe is the number of unsafe blocks the rust policy accepts in all (zero: none). */
+    maxUnsafe?: number;
+}
+/** CIParams gives the plugin the projects it owns so it can describe what CI needs for them. */
+export interface CIParams {
+    projects: Project[];
+    /**
+     * Audit is the workspace's opt-in to policy checks beyond the vulnerability scan; the zero value
+     * asks for none.
+     */
+    audit?: AuditSettings;
+}
+/** CIResult is the plugin's contribution to every generated pipeline. */
+export interface CIResult {
+    /**
+     * Stores are the package managers' download stores the pipeline caches between runs, keyed on the
+     * lockfiles that decide what is in them.
+     */
+    stores?: PackageStore[];
+    /** Toolchains are rendered as provider-native setup steps. */
+    toolchains?: Toolchain[];
+    /** Setup steps run in `smith ci setup`, in order, from the workspace root. */
+    setup?: Step[];
+    /** Audit steps run in `smith ci audit`. */
+    audit?: Step[];
+    /**
+     * PostRelease steps run at the end of `smith ci release`, whether or not anything was released,
+     * with the release's credentials: work that must follow every push to the release branch (setting
+     * a registry description from a file). They run only after a release that did not fail, from the
+     * workspace root, and a step that is not Blocking only warns.
+     */
+    postRelease?: Step[];
+    /** Credentials names the environment variables `smith ci release` needs. */
+    credentials?: Credential[];
+    /**
+     * Permissions are the GitHub Actions token permissions the release needs beyond the defaults
+     * ("packages: write" to push to ghcr.io). Other providers have no such permissions and ignore
+     * them.
+     */
+    permissions?: string[];
+    /**
+     * Authenticate are provider-native steps that sign in to a private registry before setup (Azure
+     * Pipelines' npmAuthenticate@0, say). A provider the plugin gives no step for gets none: its
+     * credentials come from the environment instead.
+     */
+    authenticate?: Toolchain[];
+}
+/** CancelParams are the params of the cancel notification. */
+export interface CancelParams {
+    /**
+     * ID is the id of the in-flight request to stop. An id the plugin does not know, or whose request
+     * is already answered, is ignored.
+     */
+    id: number;
+}
+/** Capabilities are the optional methods a plugin implements. */
+export interface Capabilities {
+    discover?: boolean;
+    generate?: boolean;
+    version?: boolean;
+    publish?: boolean;
+    ci?: boolean;
+    doctor?: boolean;
+    /** Contribute is a convention plugin's: it adds tasks to projects other plugins discovered. */
+    contribute?: boolean;
+    /** Remove cleans up a removed project's traces outside its directory. */
+    remove?: boolean;
+    /** Published reports what a registry has of a project. */
+    published?: boolean;
+    /** Dependencies installs and uninstalls packages in its projects. */
+    dependencies?: boolean;
+    /** Declarations lists and rewrites declared dependency specs (sync, up). */
+    declarations?: boolean;
+    /** Latest reports the newest releases of dependencies and pinned tools. */
+    latest?: boolean;
+    /**
+     * 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.
+     */
+    cancel?: boolean;
+}
+/**
+ * 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.
+ */
+export interface ContributeParams {
+    projects: Project[];
+}
+/** ContributeResult is what a convention adds, by project name. */
+export interface ContributeResult {
+    projects?: Record<string, Contribution>;
+}
+/** Contribution is a convention's addition to one project. */
+export interface Contribution {
+    /** Tasks are new tasks. A task the project already has is kept as it is. */
+    tasks?: Record<string, Task>;
+    /**
+     * Replace are tasks that replace the project's task of the same name, or are added when it has
+     * none.
+     */
+    replace?: Record<string, Task>;
+    /**
+     * DependsOn adds dependencies to tasks the project already has, by task name ({"lint":
+     * ["slice-check"]}).
+     */
+    dependsOn?: Record<string, string[]>;
+}
+/** Credential is a secret the release phase needs. */
+export interface Credential {
+    env: string;
+    description: string;
+    /** Required false means release works without it (e.g. a dry run target). */
+    required: boolean;
+    /**
+     * Setup gives it to `smith ci setup` (and the native job's setup) as well: installs from a
+     * private registry need it, not only the release.
+     */
+    setup?: boolean;
+    /**
+     * Tasks gives it to every step that runs tasks (verify, pack, native) as well: the remote cache's
+     * key and credentials are read there, not only by the release.
+     */
+    tasks?: boolean;
+}
+/** Declaration is one dependency one manifest declares. */
+export interface Declaration {
+    /** Project is the declaring project's name, "" for the root manifest. */
+    project?: string;
+    /** File is the manifest, workspace-relative. */
+    file: string;
+    /** Name is the dependency's name as the ecosystem compares names. */
+    name: string;
+    /** Spec is the declared range or version (^1.2.3, >=2.31), "" when the manifest gives none. */
+    spec: string;
+    /** Section is where it is declared: dependencies, devDependencies, dev... */
+    section: string;
+    /**
+     * Peer declarations state what a package works with, not what is installed: sync and up leave
+     * them alone.
+     */
+    peer?: boolean;
+    /**
+     * Rewritable is false for a spec smith must not rewrite: a URL, a git ref, a workspace alias, a
+     * compound range, environment markers.
+     */
+    rewritable: boolean;
+}
+/**
+ * DeclaredParams asks for the dependencies the plugin's projects declare (and the workspace root's
+ * manifest, when the ecosystem has one).
+ */
+export interface DeclaredParams {
+    projects: Project[];
+}
+/**
+ * DeclaredResult is every declaration, and the version installed of each name where the plugin can
+ * tell.
+ */
+export interface DeclaredResult {
+    declarations: Declaration[];
+    installed?: Record<string, string>;
+}
+/** DependencyResult lists the workspace-relative files the plugin changed and notes for the user. */
+export interface DependencyResult {
+    files?: string[];
+    notes?: string[];
+}
+/** 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". */
+    id: string;
+    options?: Record<string, string>;
+}
+/**
+ * DiscoverParams asks a plugin to describe the projects behind manifests the host found. Paths are
+ * workspace-relative and use forward slashes.
+ */
+export interface DiscoverParams {
+    manifests: string[];
+}
+/**
+ * DiscoverResult describes every manifest that is a project of this plugin. A manifest the plugin
+ * does not own is simply left out.
+ */
+export interface DiscoverResult {
+    projects: Project[];
+}
+/** DoctorParams gives the plugin its projects to check. */
+export interface DoctorParams {
+    projects: Project[];
+}
+/** DoctorResult carries the plugin's findings. */
+export interface DoctorResult {
+    findings: Finding[];
+}
+/** An object with no members. */
+export type Empty = Record<string, never>;
+/** FileEdit is one file's new content, workspace-relative; Delete removes it. */
+export interface FileEdit {
+    path: string;
+    content?: string;
+    delete?: boolean;
+}
+/** Finding is one check. Every failed finding names its remedy. */
+export interface Finding {
+    check: string;
+    ok: boolean;
+    detail?: string;
+    remedy?: string;
+    /** Warning true reports a problem without failing doctor. */
+    warning?: boolean;
+    /**
+     * Fix is the change that clears a failed finding, when the plugin can write it; smith doctor
+     * --fix shows it as a diff before applying it.
+     */
+    fix?: Fix;
+}
+/**
+ * Fix is a change that clears a failed finding: files' new contents, then commands to run, and
+ * questions the user answers first. Every part is optional; the host shows all of it before
+ * applying anything.
+ *
+ * A host that does not know Steps or Choices ignores them, so a plugin marks a fix Safe only when
+ * its Files alone are sound.
+ */
+export interface Fix {
+    description: string;
+    /**
+     * Safe marks a fix that only restores what smith or the plugin owns and loses nothing of the
+     * user's; doctor --fix --yes applies only safe fixes with no Choices. Any other fix is asked
+     * about before it runs.
+     */
+    safe: boolean;
+    /** Files are written first, as whole new contents. */
+    files?: FileEdit[];
+    /**
+     * Steps run after the files, in order, from the workspace root; the first one that fails stops
+     * the rest.
+     */
+    steps?: FixStep[];
+    /**
+     * Choices are questions the user answers before the fix applies, in order. The answer's Fix is
+     * added to this one: its files and steps come after this fix's own. A fix with Choices is never
+     * applied unasked.
+     */
+    choices?: FixChoice[];
+    /**
+     * AppliesTo names the projects the fix is for. The host folds fixes that share a Description and
+     * name projects into one ("applies to 22 projects"), so give the same Description to the same
+     * kind of fix on every project. A fix that edits one shared file for many projects lists them all
+     * here.
+     */
+    applies_to?: string[];
+}
+/** FixChoice is a question with options, one wizard step. */
+export interface FixChoice {
+    question: string;
+    options: FixChoiceOption[];
+}
+/**
+ * FixChoiceOption is one answer: a label, and the Fix it adds when picked. The first option is the
+ * suggested one.
+ */
+export interface FixChoiceOption {
+    label: string;
+    fix: Fix;
+}
+/** FixStep is a command to run in the workspace. */
+export interface FixStep {
+    /** Description says in words what the command does. */
+    description: string;
+    /** Argv is the program and its arguments; no shell is involved. */
+    argv: string[];
+    /** Dir is where it runs, workspace-relative; empty is the workspace root. */
+    dir?: string;
+}
+/**
+ * GenerateParams asks a plugin to scaffold a project. The host chooses the directory from the kind
+ * (apps/, libs/, packages/).
+ */
+export interface GenerateParams {
+    kind: ProjectKind;
+    name: string;
+    /** Directory is workspace-relative, forward slashes; it does not exist yet. */
+    directory: string;
+    /** Workspace carries what a template needs to know about the monorepo. */
+    workspace: WorkspaceInfo;
+    /**
+     * Stack is the stack the project is created with. The plugin that writes the manifest records it
+     * there, so discovery reports it back.
+     */
+    stack?: string;
+    /**
+     * Convention is true when the plugin is asked as a workspace convention ([conventions.<name>]
+     * applying to the new project), not as one of the stack's plugins. A plugin adds only what every
+     * matching project needs then: a suite or starter files belong to the stack that names it.
+     */
+    convention?: boolean;
+    /**
+     * 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.
+     */
+    settings?: Record<string, unknown>;
+}
+/** GenerateResult lists what the plugin wrote, workspace-relative. */
+export interface GenerateResult {
+    files: string[];
+    /** Notes are printed to the user after generation. */
+    notes?: string[];
+}
+/** InitializeParams is sent once, first, by the host. */
+export interface InitializeParams {
+    /** ProtocolVersions lists every major version the host can speak. */
+    protocolVersions: number[];
+    host: Peer;
+    /** WorkspaceRoot is an absolute path using the host OS separators. */
+    workspaceRoot: string;
+}
+/** InitializeResult tells the host who the plugin is and what it can do. */
+export interface InitializeResult {
+    /** ProtocolVersion is the version the plugin chose from the host's list. */
+    protocolVersion: number;
+    plugin: Peer;
+    kind: PluginKind;
+    capabilities: Capabilities;
+    /**
+     * Concurrency is how many requests the plugin can work on at the same time; the host never has
+     * more in flight. Absent or 0 means 1, which is what every plugin that says nothing does: the
+     * host sends the next request only after the previous one is answered. N above 1 allows that
+     * many, and ConcurrencyUnlimited (-1) leaves the number to the host. Any other negative value is
+     * invalid and read as 1.
+     */
+    concurrency?: number;
+    /** Languages are the values a user passes to --lang to reach this plugin. */
+    languages?: string[];
+    /**
+     * Manifests are file base names (package.json, go.mod), or patterns of them (*.csproj), whose
+     * presence in a directory may make it a project of this plugin.
+     */
+    manifests?: string[];
+    /**
+     * Roles are the levels the plugin can be chosen for in a project's make-up (a stack, a recipe).
+     * Empty means the default of its kind (see DefaultRoles). A role is a level: there is no separate
+     * level field, because one plugin can play several (a scaffold that is also a toolchain).
+     */
+    roles?: Role[];
+    /**
+     * Provides are the slots a toolchain plugin fills: the task names it owns ("test" for a test
+     * runner). A slot is exclusive: two plugins of one project may not provide the same task.
+     */
+    provides?: string[];
+    /**
+     * Requires are plugins that must also be in the project for this one to work: a Node toolchain
+     * requires the node language plugin.
+     */
+    requires?: PluginRef[];
+    /** Conflicts are plugins that must not be in the same project. */
+    conflicts?: PluginRef[];
+    /** Stacks are ready-made stacks the plugin publishes. */
+    stacks?: Stack[];
+}
+/**
+ * Input is one input of an ActionStep. Values are written as quoted YAML strings, except true and
+ * false.
+ */
+export interface Input {
+    name: string;
+    value: string;
+}
+/**
+ * InstallParams asks a plugin to add packages to one of its projects with the ecosystem's own
+ * toolchain, or, with no project, to install every dependency of the projects it serves (a fresh
+ * clone's first step).
+ */
+export interface InstallParams {
+    /** Project is the project the packages go into; nil installs everything. */
+    project?: Project;
+    /** Projects are the projects the plugin serves, when Project is nil. */
+    projects?: Project[];
+    /**
+     * Packages are names or pinned specs as the ecosystem writes them (left-pad, requests>=2.31,
+     * github.com/pkg/errors@v0.9.1).
+     */
+    packages?: string[];
+    /**
+     * Dev adds them as development dependencies where the ecosystem has such a thing; a plugin
+     * without one says so in a note.
+     */
+    dev?: boolean;
+}
+/**
+ * LatestParams asks for the newest stable release of each dependency, and, with Tools, how the
+ * tools the plugin pins compare with their latest.
+ */
+export interface LatestParams {
+    names?: string[];
+    tools?: boolean;
+}
+/**
+ * LatestResult maps each name to its newest stable version. A name the registry could not be asked
+ * about is in Unreachable, with the reason; a name the registry does not have is in neither.
+ */
+export interface LatestResult {
+    latest?: Record<string, string>;
+    unreachable?: Record<string, string>;
+    tools?: ToolPin[];
+}
+/**
+ * PackageStore is where a package manager keeps what it downloaded (npm's ~/.npm, Go's module
+ * cache). A generated pipeline restores it before setup and saves it after a run, keyed on Files,
+ * so `npm ci` or `go mod download` fetches only what changed. A pull request from a fork restores
+ * it and never writes the base repository's cache.
+ */
+export interface PackageStore {
+    /** Name identifies the store ("npm", "go") and is part of its cache key. */
+    name: string;
+    /** Path is the store's default location, which GitHub Actions caches as it is ("~/.npm"). */
+    path: string;
+    /**
+     * Env is the environment variable that moves the store (NPM_CONFIG_CACHE, GOMODCACHE). Azure
+     * Pipelines and GitLab CI cache only directories under their own workspace, so they set it to one
+     * and cache that instead.
+     */
+    env: string;
+    /**
+     * Files are the lockfiles that key the store: workspace-relative paths or globs. GitLab CI keys
+     * on the first two.
+     */
+    files: string[];
+}
+/** Peer names one side of the connection. */
+export interface Peer {
+    name: string;
+    version: string;
+}
+/**
+ * PluginKind separates plugins that understand a language from plugins that add to projects a
+ * language plugin discovered (toolchains, structure rules, scaffolds, deploy targets), which are
+ * all of kind convention.
+ *
+ * Plugin kinds.
+ */
+export type PluginKind = 'language' | 'convention';
+/**
+ * PluginRef names the plugins a requirement or a conflict is about. Every field set must match; at
+ * least one must be set.
+ */
+export interface PluginRef {
+    /** Level is the role the plugin is chosen for in the project. */
+    level?: Role;
+    /**
+     * Name is the plugin's name, or for a language plugin one of its languages ("node",
+     * "javascript").
+     */
+    name?: string;
+    /** Slot is a task the plugin provides ("test"). */
+    slot?: string;
+}
+/** Project is one unit of the monorepo as a plugin sees it. */
+export interface Project {
+    /** Name is unique across the workspace; it is what users type. */
+    name: string;
+    /** Root is the workspace-relative directory, forward slashes. */
+    root: string;
+    language: string;
+    kind: ProjectKind;
+    /**
+     * Exports are the identifiers other projects import this one by: an npm package name, a Go module
+     * path, a Python import name.
+     */
+    exports?: string[];
+    /**
+     * Imports are identifiers this project's sources import. The host keeps the ones another project
+     * exports and turns them into graph edges.
+     */
+    imports?: string[];
+    /** Version is the version recorded in the manifest, if it has one. */
+    version?: string;
+    /**
+     * Toolchain is the version of the compiler or runtime the project's tasks run with ("node
+     * 20.11.0", "go 1.23.4"), as the plugin probed it. It goes into every task's cache key, so a
+     * result from another version is a miss. Empty when the plugin cannot tell, and then it is left
+     * out.
+     */
+    toolchain?: string;
+    /**
+     * PublishTo is where a package publishes, when its manifest says: "pub.dev" for the public
+     * registry that takes a package only from a run on its tag (so a release does not publish it
+     * itself), "none" for a package that is never published, or a repository URL. Empty when the
+     * plugin does not say.
+     */
+    publishTo?: string;
+    /**
+     * Description is the one-line description the manifest records (package.json description,
+     * pyproject.toml project.description, the pom's <description>), if it has one. Conventions use it
+     * where a registry asks for a summary.
+     */
+    description?: string;
+    /**
+     * TagPrefix overrides the release tag prefix; empty means "<name>@". Go modules use "<root>/v" so
+     * `go get` can resolve the tag.
+     */
+    tagPrefix?: string;
+    tasks?: Record<string, Task>;
+    tags?: string[];
+    /** Stack is the stack recorded in the project's manifest, if any. */
+    stack?: string;
+    /**
+     * 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.
+     */
+    settings?: Record<string, Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    registries?: Registries;
+}
+/**
+ * ProjectKind is the universal kind vocabulary.
+ *
+ * Project kinds. An app is deployed, never published; a lib is internal and never published; a
+ * package is published.
+ */
+export type ProjectKind = 'app' | 'lib' | 'package';
+/** PublishParams asks a plugin to publish one project at one version. */
+export interface PublishParams {
+    project: Project;
+    version: string;
+    dryRun?: boolean;
+    /**
+     * Assets, when set, asks the plugin to build the files attached to the release (an app's
+     * per-platform binaries) instead of publishing to a registry.
+     */
+    assets?: AssetSpec;
+    /**
+     * Platform, when set, is the "os/arch" (Go's spelling) of the runner a native project is
+     * published from: each native job publishes its own platform's build (a VS Code extension's
+     * target) and nothing else.
+     */
+    platform?: string;
+    /**
+     * Tagged says the publish runs on the project's own tag, in the run the registry trusts
+     * (pub.dev's automated publishing); a registry that takes a package only from such a run is
+     * published to only then.
+     */
+    tagged?: boolean;
+    /**
+     * Commit is the full hash of the commit being released, and Branch the release branch, for a
+     * plugin that tags what it publishes with them (a container image's sha-<short> and branch tags).
+     * Empty when unknown.
+     */
+    commit?: string;
+    branch?: string;
+}
+/**
+ * PublishResult reports what happened. Skipped with a reason is a success: an already-published
+ * version makes a re-run safe.
+ */
+export interface PublishResult {
+    published: boolean;
+    skipped?: string;
+    registry?: string;
+    /**
+     * Assets are the workspace-relative files built for the release, in upload order; in a dry run,
+     * the files that would be built.
+     */
+    assets?: string[];
+    /**
+     * AssetPlatforms maps each archive among Assets to the "os/arch" it was built for, so the host
+     * can describe them (package manager manifests).
+     */
+    assetPlatforms?: Record<string, string>;
+    /** Binary is the executable's name inside each archive, without ".exe". */
+    binary?: string;
+    /**
+     * Images are the container images pushed, one per registry, for a deploy step or a GitOps
+     * manifest to refer to by digest.
+     */
+    images?: PublishedImage[];
+}
+/** PublishedImage is one container image a release pushed. */
+export interface PublishedImage {
+    /** Reference is the image without a tag: ghcr.io/acme/api. */
+    reference: string;
+    /** Tags are the tags pushed, in the order they were. */
+    tags: string[];
+    /**
+     * Digest is the manifest digest the registry holds ("sha256:..."); empty when it could not be
+     * read.
+     */
+    digest?: string;
+}
+/** PublishedParams asks which version of a project its registry has. */
+export interface PublishedParams {
+    project: Project;
+}
+/** PublishedResult is the newest version the registry has of a project. */
+export interface PublishedResult {
+    /**
+     * Version is empty when the registry does not know the project: its first release is still to
+     * come.
+     */
+    version?: string;
+    /** Registry names where the plugin looked, for messages. */
+    registry?: string;
+    /**
+     * Unreachable is true when the registry could not be asked (offline, an error), so nothing can be
+     * concluded; Detail says why.
+     */
+    unreachable?: boolean;
+    detail?: string;
+}
+/**
+ * Registries are the registries a project uses, set by the host from smith.toml: Install is where
+ * the workspace installs packages from, Publish where the project is published. Nil, or a nil
+ * member, means the public registry, as before.
+ */
+export interface Registries {
+    install?: Registry;
+    publish?: Registry;
+    /**
+     * NoPublish means smith.toml says registry = "none": the release versions and tags the project
+     * and publishes it to no registry (a registry that builds from the tag, such as JitPack, does the
+     * rest).
+     */
+    noPublish?: boolean;
+}
+/**
+ * Registry is a package registry smith.toml names in [registries.<name>]: a private feed (Azure
+ * Artifacts, GitHub Packages, any token-protected registry) a language plugin installs from or
+ * publishes to. Each URL is optional; a plugin reads the one for its ecosystem.
+ */
+export interface Registry {
+    name: string;
+    /** Auth is how the registry is signed in to: AuthAzureArtifacts, AuthGitHubPackages or AuthToken. */
+    auth: string;
+    /** TokenEnv is the environment variable holding the token, for AuthToken. */
+    tokenEnv?: string;
+    /** NPM is the npm registry URL. */
+    npm?: string;
+    /** PyPI is the simple index pip installs from; PyPIUpload is where twine uploads. */
+    pypi?: string;
+    pypiUpload?: string;
+    /** NuGet is the NuGet v3 service index. */
+    nuget?: string;
+    /**
+     * Maven is the Maven repository packages deploy to: an https URL, or MavenGitHub for the GitHub
+     * Packages repository of the repository the release runs in.
+     */
+    maven?: string;
+}
+/**
+ * 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).
+ */
+export interface RemoveParams {
+    project: Project;
+    /** DryRun asks what would change, without changing it. */
+    dryRun?: boolean;
+}
+/**
+ * RemoveResult lists the workspace-relative files the plugin changed (or, in a dry run, would
+ * change), and notes for the user.
+ */
+export interface RemoveResult {
+    files?: string[];
+    notes?: string[];
+}
+/** Request is a JSON-RPC 2.0 request, or a notification when ID is nil. */
+export interface Request {
+    jsonrpc: string;
+    id?: number;
+    method: string;
+    params?: unknown;
+}
+/** Response is a JSON-RPC 2.0 response. Exactly one of Result and Error is set. */
+export interface Response {
+    jsonrpc: string;
+    id: number | null;
+    result?: unknown;
+    error?: ResponseError;
+}
+/** ResponseError is a JSON-RPC 2.0 error object. */
+export interface ResponseError {
+    code: number;
+    message: string;
+}
+/** Rewrite changes one declaration's spec. */
+export interface Rewrite {
+    declaration: Declaration;
+    spec: string;
+}
+/** RewriteParams asks a plugin to change declared specs in place. */
+export interface RewriteParams {
+    changes: Rewrite[];
+}
+/**
+ * Role is a part a plugin plays in a project's make-up: its level. Some levels are exclusive (one
+ * plugin per project, or per slot) and the others additive (any number, and they only add).
+ */
+export type Role = 'language' | 'toolchain' | 'structure' | 'scaffold' | 'deploy';
+/**
+ * Stack is a named set of plugins a project is built with: one language plugin, and the toolchain,
+ * structure, scaffold and deploy plugins on top. Plugins are named, never assumed to be built in.
+ */
+export interface Stack {
+    name: string;
+    description?: string;
+    /** Language is the language plugin that discovers the stack's projects. */
+    language: string;
+    /**
+     * Toolchain plugins decide how projects build, test and lint, in order: a later one may replace a
+     * task an earlier one added.
+     */
+    toolchain?: string[];
+    structure?: string[];
+    /** Scaffold generates new projects; empty means the language plugin does. */
+    scaffold?: string;
+    deploy?: string[];
+}
+/** Step is one command a CI phase runs. */
+export interface Step {
+    name: string;
+    command: string[];
+    /** Dir is the workspace-relative directory to run in; empty means the workspace root. */
+    dir?: string;
+    /** Blocking false makes a failure a warning instead of an error. */
+    blocking: boolean;
+    /**
+     * CacheFiles are workspace-relative files whose content decides what an audit step finds (a
+     * lockfile). When any exists, smith remembers a passing run per content of these files and per
+     * day, in the task cache, and skips the step while both are unchanged; a failing run is always
+     * repeated. Only the audit phase reads it.
+     */
+    cacheFiles?: string[];
+}
+/** Task is a command the host can run, hash and cache. */
+export interface Task {
+    /** Command is an argv array; it is never passed through a shell. */
+    command: string[];
+    /** Cwd is workspace-relative; empty means the project root. */
+    cwd?: string;
+    env?: Record<string, string>;
+    /**
+     * Inputs are globs relative to the project root. Empty means every tracked or
+     * untracked-but-not-ignored file of the project.
+     */
+    inputs?: string[];
+    /** Outputs are directories relative to the project root, restored on a cache hit. */
+    outputs?: string[];
+    /**
+     * DependsOn lists task names: "build" runs this project's build first, "^build" runs the build of
+     * every project this one imports first.
+     */
+    dependsOn?: string[];
+    cache?: boolean;
+    /** Description is shown by `smith explain` and the TUI. */
+    description?: string;
+    /**
+     * Verify asks CI's verify phase (smith ci verify) to run the task too, after lint, typecheck,
+     * test and build, for the affected projects that have it: an app's container image, so a broken
+     * Dockerfile fails the pull request, not the release. It is skipped, with a warning, where its
+     * program is not installed.
+     */
+    verify?: boolean;
+    /**
+     * Serve names a task ("web:start", or "start" in the same project) that smith starts before this
+     * one and stops after it, whatever the result: the app an end-to-end suite tests. Its own
+     * dependsOn run first.
+     */
+    serve?: string;
+    /**
+     * ServeURL is what smith waits for (an HTTP 2xx) before it runs the task, and passes to it as
+     * E2E_BASE_URL. Empty: the task starts at once.
+     */
+    serveUrl?: string;
+    /** ServeTimeout is how long to wait for ServeURL, as a Go duration ("60s"); empty means 60s. */
+    serveTimeout?: string;
+}
+/**
+ * ToolPin is a tool the plugin installs at a pinned version (in CI, the dev container, the venv)
+ * against the newest release; informational.
+ */
+export interface ToolPin {
+    name: string;
+    pinned: string;
+    /** Latest is empty when its release feed could not be reached. */
+    latest?: string;
+    /** Newer is true when Latest is a release the pin does not cover. */
+    newer?: boolean;
+}
+/**
+ * Toolchain is a runtime the pipeline must install, and how. Plugins asking for the same name share
+ * one setup step (the first plugin's).
+ */
+export interface Toolchain {
+    name: string;
+    version: string;
+    /** GitHub is the GitHub Actions step that installs it (an action). */
+    github?: ActionStep;
+    /** Azure is the Azure Pipelines step that installs it (a task). */
+    azure?: ActionStep;
+    /**
+     * Install is a shell command that installs it, run on a provider the plugin gives no native step
+     * for.
+     */
+    install?: string;
+    /**
+     * Devcontainer is the dev container feature that installs it at the same version, so the editor's
+     * container matches CI.
+     */
+    devcontainer?: DevcontainerFeature;
+}
+/** UninstallParams asks a plugin to remove packages from one of its projects. */
+export interface UninstallParams {
+    project: Project;
+    packages: string[];
+}
+/** VersionParams asks a plugin to record a new version in a project manifest. */
+export interface VersionParams {
+    project: Project;
+    version: string;
+    /**
+     * Dependencies maps exported identifiers of other workspace projects to their new versions, so
+     * the plugin can update dependency ranges.
+     */
+    dependencies?: Record<string, string>;
+    dryRun?: boolean;
+}
+/** VersionResult lists the files that were (or, in a dry run, would be) changed. */
+export interface VersionResult {
+    files: string[];
+}
+/** WorkspaceInfo is the subset of workspace settings plugins may use. */
+export interface WorkspaceInfo {
+    name: string;
+    /** Scope is the npm scope for packages, with its @ (e.g. "@acme"). */
+    scope?: string;
+    /** ModulePrefix is the Go module path prefix, e.g. github.com/acme/repo. */
+    modulePrefix?: string;
+}
+/** Every method of the protocol with its params, its result and the capability a plugin advertises to be asked it. */
+export interface ProtocolMethods {
+    /**
+     * The first request, sent once by the host. The plugin picks a protocol version from the host's
+     * list and answers who it is and what it can do.
+     */
+    initialize: {
+        params: InitializeParams;
+        result: InitializeResult;
+        capability: null;
+    };
+    /** The last request. The plugin answers an empty object and exits. */
+    shutdown: {
+        params: Empty;
+        result: Empty;
+        capability: null;
+    };
+    /**
+     * A notification, so it gets no response: the host asks the plugin to stop the in-flight request
+     * with the given id. The plugin then answers that request, with its result if the work was
+     * already done or with the request-cancelled error. An id that is unknown or already answered is
+     * ignored. The host sends it only to a plugin that advertised the capability.
+     */
+    cancel: {
+        params: CancelParams;
+        result: null;
+        capability: 'cancel';
+    };
+    /**
+     * Describes the projects behind manifests the host found; a language plugin's way into the
+     * workspace.
+     */
+    discover: {
+        params: DiscoverParams;
+        result: DiscoverResult;
+        capability: 'discover';
+    };
+    /** Writes the starter files of a new project. */
+    generate: {
+        params: GenerateParams;
+        result: GenerateResult;
+        capability: 'generate';
+    };
+    /** Records a release version in a project's manifest. */
+    'version/write': {
+        params: VersionParams;
+        result: VersionResult;
+        capability: 'version';
+    };
+    /** Publishes one project at one version, or builds the files attached to a release. */
+    publish: {
+        params: PublishParams;
+        result: PublishResult;
+        capability: 'publish';
+    };
+    /** Describes what a generated pipeline needs for the plugin's projects. */
+    ci: {
+        params: CIParams;
+        result: CIResult;
+        capability: 'ci';
+    };
+    /** Checks the plugin's projects and reports findings, each with its remedy and, optionally, a fix. */
+    doctor: {
+        params: DoctorParams;
+        result: DoctorResult;
+        capability: 'doctor';
+    };
+    /**
+     * Asks a convention (toolchain, structure, deploy) for the tasks and dependencies it adds to
+     * projects other plugins discovered.
+     */
+    contribute: {
+        params: ContributeParams;
+        result: ContributeResult;
+        capability: 'contribute';
+    };
+    /** Lets a plugin clean up what it owns outside a project's directory after the project is removed. */
+    remove: {
+        params: RemoveParams;
+        result: RemoveResult;
+        capability: 'remove';
+    };
+    /** Asks which version of a project its registry has, so a release can check its tags against it. */
+    published: {
+        params: PublishedParams;
+        result: PublishedResult;
+        capability: 'published';
+    };
+    /**
+     * Adds packages to a project with the ecosystem's own toolchain, or, with no project, installs
+     * every dependency of the projects the plugin serves.
+     */
+    'dependencies/install': {
+        params: InstallParams;
+        result: DependencyResult;
+        capability: 'dependencies';
+    };
+    /** Removes packages from a project. */
+    'dependencies/uninstall': {
+        params: UninstallParams;
+        result: DependencyResult;
+        capability: 'dependencies';
+    };
+    /** Lists the dependencies the manifests of the plugin's projects declare. */
+    'dependencies/declared': {
+        params: DeclaredParams;
+        result: DeclaredResult;
+        capability: 'declarations';
+    };
+    /** Changes declared dependency specs in place. */
+    'dependencies/rewrite': {
+        params: RewriteParams;
+        result: DependencyResult;
+        capability: 'declarations';
+    };
+    /**
+     * Asks registries for the newest releases of dependencies, and how the tools the plugin pins
+     * compare with theirs.
+     */
+    'dependencies/latest': {
+        params: LatestParams;
+        result: LatestResult;
+        capability: 'latest';
+    };
+}
+export type MethodName = keyof ProtocolMethods;
+export type ParamsOf<M extends MethodName> = ProtocolMethods[M]['params'];
+export type ResultOf<M extends MethodName> = ProtocolMethods[M]['result'];
+/** The names of the capability flags: the optional methods a plugin implements. */
+export type CapabilityName = keyof Capabilities;