@pikku/inspector 0.12.111 → 0.12.113

package/dist/add/add-define-contributors.d.ts

@@ -0,0 +1,10 @@
+import * as ts from 'typescript';
+import type { InspectorLogger, InspectorState } from '../types.js';
+/**
+ * Detect `defineContributors({ [name]: { dev?, deploy? } })` and record, per
+ * name, the module and export of each variant. A name defined twice, or a
+ * variant a host could not import by itself, is a critical error: a contributor
+ * that silently drops out would leave the host without the service it opted in
+ * to.
+ */
+export declare function addDefineContributors(logger: InspectorLogger, node: ts.Node, checker: ts.TypeChecker, state: InspectorState): void;

package/dist/add/add-define-contributors.js

@@ -0,0 +1,98 @@
+import * as ts from 'typescript';
+import { ErrorCode } from '../error-codes.js';
+import { callsImportedDefiner, exportedName } from './add-analytics.js';
+const DEFINE_CONTRIBUTORS = 'defineContributors';
+const VARIANTS = ['dev', 'deploy'];
+const propertyKey = (name) => ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
+/**
+ * Where an exported contributor const lives and what it is exported as. A
+ * host imports exactly this, so a variant that is inline, not exported, or
+ * built by a call has no answer and is reported instead.
+ */
+const resolveVariant = (value, checker) => {
+    if (!ts.isIdentifier(value)) {
+        return `must be a reference to an exported const so a host can import just that variant, got: ${value.getText()}`;
+    }
+    let symbol = checker.getSymbolAtLocation(value);
+    if (symbol && symbol.flags & ts.SymbolFlags.Alias) {
+        symbol = checker.getAliasedSymbol(symbol);
+    }
+    const declaration = symbol?.valueDeclaration ?? symbol?.declarations?.[0];
+    if (!declaration ||
+        !ts.isVariableDeclaration(declaration) ||
+        !ts.isIdentifier(declaration.name)) {
+        return `'${value.text}' does not resolve to a const declaration`;
+    }
+    const exported = exportedName(declaration, declaration.name, checker);
+    if (!exported) {
+        return `'${value.text}' is not exported by ${declaration.getSourceFile().fileName}`;
+    }
+    return { module: declaration.getSourceFile().fileName, export: exported };
+};
+/**
+ * Detect `defineContributors({ [name]: { dev?, deploy? } })` and record, per
+ * name, the module and export of each variant. A name defined twice, or a
+ * variant a host could not import by itself, is a critical error: a contributor
+ * that silently drops out would leave the host without the service it opted in
+ * to.
+ */
+export function addDefineContributors(logger, node, checker, state) {
+    if (!ts.isCallExpression(node))
+        return;
+    if (!callsImportedDefiner(node.expression, checker, DEFINE_CONTRIBUTORS))
+        return;
+    const fail = (code, message) => logger.critical(code, message);
+    const notStatic = (message) => fail(ErrorCode.CONTRIBUTORS_NOT_STATIC, message);
+    const [argument] = node.arguments;
+    if (!argument || !ts.isObjectLiteralExpression(argument)) {
+        notStatic(`defineContributors must be called with an object literal keyed by contributor name${argument ? `, got: ${argument.getText()}` : ''}`);
+        return;
+    }
+    for (const property of argument.properties) {
+        const name = ts.isPropertyAssignment(property)
+            ? propertyKey(property.name)
+            : undefined;
+        if (!name || !ts.isPropertyAssignment(property)) {
+            notStatic(`defineContributors takes { name: { dev?, deploy? } } entries, got: ${property.getText()}`);
+            continue;
+        }
+        if (!ts.isObjectLiteralExpression(property.initializer)) {
+            notStatic(`Contributor '${name}' must be an object literal with dev and/or deploy, got: ${property.initializer.getText()}`);
+            continue;
+        }
+        const variants = {};
+        let valid = true;
+        for (const variant of property.initializer.properties) {
+            const key = ts.isPropertyAssignment(variant)
+                ? propertyKey(variant.name)
+                : undefined;
+            if (!key ||
+                !ts.isPropertyAssignment(variant) ||
+                !VARIANTS.includes(key)) {
+                notStatic(`Contributor '${name}' takes only dev and deploy, got: ${variant.getText()}`);
+                valid = false;
+                continue;
+            }
+            const ref = resolveVariant(variant.initializer, checker);
+            if (typeof ref === 'string') {
+                notStatic(`Contributor '${name}' ${key} ${ref}`);
+                valid = false;
+                continue;
+            }
+            variants[key] = ref;
+        }
+        if (!valid)
+            continue;
+        if (!variants.dev && !variants.deploy) {
+            notStatic(`Contributor '${name}' declares neither dev nor deploy`);
+            continue;
+        }
+        const manifest = (state.contributorsManifest ??= {});
+        if (manifest[name]) {
+            fail(ErrorCode.CONTRIBUTOR_NAME_DUPLICATED, `Contributor '${name}' is defined twice. A contributor name belongs to one defineContributors entry.`);
+            continue;
+        }
+        logger.debug(`• Found ${DEFINE_CONTRIBUTORS}: ${name}`);
+        manifest[name] = variants;
+    }
+}

package/dist/add/add-pikku-studio.d.ts

@@ -1,14 +1,14 @@
 import * as ts from 'typescript';
 import type { InspectorState, InspectorLogger } from '../types.js';
 /**
- * Detect `pikkuStudio({ title, screens })` and record it as the package's
+ * Detect `definePlugin({ title, screens })` and record it as the package's
  * `studio` metadata. Every field must be a literal: one that is not is
  * reported and its screen left out, since a screen the host cannot read would
  * otherwise vanish with no sign.
  */
 export declare function addPikkuStudio(node: ts.Node, state: InspectorState, logger: InspectorLogger): void;
 /**
- * The checks on `pikkuStudio` that need the whole package: every title is a
+ * The checks on `definePlugin` that need the whole package: every title is a
  * key in the addon's `messages/en.json` (a key missing from another locale is
  * a warning), and every nav badge names one of the addon's functions.
  */

package/dist/add/add-pikku-studio.js

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import { existsSync, readFileSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { dirname, join } from 'path';
 import { ErrorCode } from '../error-codes.js';
 const SCOPES = ['studio', 'team', 'project'];
@@ -97,7 +97,7 @@ const readNav = (node, fail) => {
 };
 const readScreen = (element, fail) => {
     if (!ts.isObjectLiteralExpression(element)) {
-        fail(`A pikkuStudio screen must be an object literal, got: ${element.getText()}`);
+        fail(`A definePlugin screen must be an object literal, got: ${element.getText()}`);
         return undefined;
     }
     let path;
@@ -110,6 +110,7 @@ const readScreen = (element, fail) => {
     let scopes;
     let component;
     let app;
+    let agent;
     let ok = true;
     for (const field of element.properties) {
         const key = propName(field);
@@ -136,6 +137,8 @@ const readScreen = (element, fail) => {
             read = replaces = booleanLiteral(value);
         else if (key === 'needsApp')
             read = needsApp = booleanLiteral(value);
+        else if (key === 'agent')
+            read = agent = ts.isStringLiteral(value) ? value.text : undefined;
         else if (key === 'layout')
             read = layout = oneOf(value, ['bare']);
         else if (key === 'scopes') {
@@ -166,7 +169,7 @@ const readScreen = (element, fail) => {
     if (!ok)
         return undefined;
     if (!path || !title || !scope || (!component && !app)) {
-        fail(`A pikkuStudio screen needs a literal path, title and scope, and either a lazy component or an app: ${element.getText()}`);
+        fail(`A definePlugin screen needs a literal path, title and scope, and either a lazy component or an app: ${element.getText()}`);
         return undefined;
     }
     if (component && app) {
@@ -182,11 +185,12 @@ const readScreen = (element, fail) => {
         ...(needsApp !== undefined ? { needsApp } : {}),
         ...(layout ? { layout } : {}),
         ...(scopes ? { scopes } : {}),
+        ...(agent !== undefined ? { agent } : {}),
         ...(component ? { component } : { app: app }),
     };
 };
 /**
- * Detect `pikkuStudio({ title, screens })` and record it as the package's
+ * Detect `definePlugin({ title, screens })` and record it as the package's
  * `studio` metadata. Every field must be a literal: one that is not is
  * reported and its screen left out, since a screen the host cannot read would
  * otherwise vanish with no sign.
@@ -195,7 +199,8 @@ export function addPikkuStudio(node, state, logger) {
     if (!ts.isCallExpression(node))
         return;
     const { expression, arguments: args } = node;
-    if (!ts.isIdentifier(expression) || expression.text !== 'pikkuStudio')
+    if (!ts.isIdentifier(expression) ||
+        (expression.text !== 'definePlugin' && expression.text !== 'pikkuStudio'))
         return;
     const [firstArg] = args;
     if (!firstArg || !ts.isObjectLiteralExpression(firstArg))
@@ -206,7 +211,7 @@ export function addPikkuStudio(node, state, logger) {
     for (const prop of firstArg.properties) {
         const key = propName(prop);
         if (!key || !ts.isPropertyAssignment(prop)) {
-            fail(`A pikkuStudio field must be a literal, got: ${prop.getText()}`);
+            fail(`A definePlugin field must be a literal, got: ${prop.getText()}`);
             continue;
         }
         if (key === 'title') {
@@ -214,12 +219,12 @@ export function addPikkuStudio(node, state, logger) {
                 title = prop.initializer.text;
             }
             else {
-                fail(`pikkuStudio's title must be a literal, got: ${prop.initializer.getText()}`);
+                fail(`definePlugin's title must be a literal, got: ${prop.initializer.getText()}`);
             }
         }
         else if (key === 'screens') {
             if (!ts.isArrayLiteralExpression(prop.initializer)) {
-                fail(`pikkuStudio's screens must be an array literal, got: ${prop.initializer.getText()}`);
+                fail(`definePlugin's screens must be an array literal, got: ${prop.initializer.getText()}`);
                 continue;
             }
             for (const element of prop.initializer.elements) {
@@ -230,17 +235,17 @@ export function addPikkuStudio(node, state, logger) {
         }
     }
     if (!title) {
-        fail(`pikkuStudio needs a literal title`);
+        fail(`definePlugin needs a literal title`);
         return;
     }
     const seen = new Set();
     for (const screen of screens) {
         if (seen.has(screen.path)) {
-            logger.critical(ErrorCode.STUDIO_SCREEN_PATH_DUPLICATE, `pikkuStudio declares two screens at '${screen.path}'; each screen needs its own path`);
+            logger.critical(ErrorCode.STUDIO_SCREEN_PATH_DUPLICATE, `definePlugin declares two screens at '${screen.path}'; each screen needs its own path`);
         }
         seen.add(screen.path);
     }
-    logger.debug(`• Found pikkuStudio: ${title} (${screens.length} screens)`);
+    logger.debug(`• Found definePlugin: ${title} (${screens.length} screens)`);
     state.studio = {
         title,
         file: node.getSourceFile().fileName,
@@ -259,6 +264,34 @@ const packageRoot = (file) => {
         dir = parent;
     }
 };
+const AGENT_NAME = /^[a-z][a-z0-9-]*$/;
+const STUDIO_AGENT = /^studio:[a-z][a-z0-9-]*$/;
+/** The text of a file that exists and is not blank, else undefined. */
+const readNonEmpty = (file) => {
+    try {
+        if (!statSync(file).isFile())
+            return undefined;
+        const text = readFileSync(file, 'utf-8');
+        return text.trim() === '' ? undefined : text;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The `key: value` lines of a leading `---` block; undefined when there is none. */
+const readFrontmatter = (text) => {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+    if (!match)
+        return undefined;
+    const fields = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const pair = /^([A-Za-z][\w-]*):\s*(.*?)\s*$/.exec(line);
+        if (!pair)
+            continue;
+        fields[pair[1]] = pair[2].replace(/^(['"])(.*)\1$/, '$2');
+    }
+    return fields;
+};
 const readCatalog = (file) => {
     try {
         return JSON.parse(readFileSync(file, 'utf-8'));
@@ -268,7 +301,7 @@ const readCatalog = (file) => {
     }
 };
 /**
- * The checks on `pikkuStudio` that need the whole package: every title is a
+ * The checks on `definePlugin` that need the whole package: every title is a
  * key in the addon's `messages/en.json` (a key missing from another locale is
  * a warning), and every nav badge names one of the addon's functions.
  */
@@ -282,7 +315,7 @@ export function validatePikkuStudio(logger, state) {
     const en = messagesDir ? readCatalog(join(messagesDir, 'en.json')) : undefined;
     for (const key of new Set(keys)) {
         if (!en || !Object.hasOwn(en, key)) {
-            logger.critical(ErrorCode.STUDIO_MESSAGE_KEY_MISSING, `pikkuStudio uses the message key '${key}', which is missing from the addon's messages/en.json`);
+            logger.critical(ErrorCode.STUDIO_MESSAGE_KEY_MISSING, `definePlugin uses the message key '${key}', which is missing from the addon's messages/en.json`);
         }
     }
     if (messagesDir && existsSync(messagesDir)) {
@@ -293,12 +326,52 @@ export function validatePikkuStudio(logger, state) {
             const catalog = readCatalog(join(messagesDir, name)) ?? {};
             for (const key of new Set(keys)) {
                 if (!Object.hasOwn(catalog, key)) {
-                    logger.warn(`pikkuStudio uses the message key '${key}', which is missing from the addon's messages/${name}`);
+                    logger.warn(`definePlugin uses the message key '${key}', which is missing from the addon's messages/${name}`);
                 }
             }
         }
     }
     for (const screen of studio.screens) {
+        const agent = screen.agent;
+        if (agent !== undefined) {
+            const invalid = (reason) => logger.critical(ErrorCode.STUDIO_SCREEN_AGENT_INVALID, `Screen '${screen.path}' has the agent '${agent}', ${reason}`);
+            if (agent.startsWith('studio:')) {
+                // An agent Studio ships: pikku cannot see it, so only the format is checked.
+                if (!STUDIO_AGENT.test(agent)) {
+                    invalid("which is not a valid agent: use a name for an agent the addon ships (lowercase letters, digits and hyphens, starting with a letter) or 'studio:<name>' for one Studio ships");
+                }
+            }
+            else if (!AGENT_NAME.test(agent)) {
+                invalid("which is not a valid agent: use a name for an agent the addon ships (lowercase letters, digits and hyphens, starting with a letter) or 'studio:<name>' for one Studio ships");
+            }
+            else {
+                const text = root
+                    ? readNonEmpty(join(root, 'agents', `${agent}.md`))
+                    : undefined;
+                const fields = text === undefined ? undefined : readFrontmatter(text);
+                if (text === undefined) {
+                    invalid(`but the addon has no non-empty agents/${agent}.md`);
+                }
+                else if (!fields) {
+                    invalid(`whose agents/${agent}.md has no frontmatter; it needs a title and a description`);
+                }
+                else {
+                    for (const field of ['title', 'description']) {
+                        const key = fields[field];
+                        if (!key) {
+                            invalid(`whose agents/${agent}.md frontmatter has no ${field}; it must be a message key`);
+                        }
+                        else if (!en || !Object.hasOwn(en, key)) {
+                            logger.critical(ErrorCode.STUDIO_MESSAGE_KEY_MISSING, `definePlugin uses the message key '${key}', which is missing from the addon's messages/en.json`);
+                        }
+                        else if (field === 'title')
+                            screen.agentTitle = key;
+                        else
+                            screen.agentDescription = key;
+                    }
+                }
+            }
+        }
         const badge = screen.nav?.badge;
         if (badge !== undefined && !state.functions.meta[badge]) {
             logger.critical(ErrorCode.STUDIO_BADGE_FUNCTION_NOT_FOUND, `Screen '${screen.path}' has the nav badge '${badge}', which names no function in this addon`);

package/dist/add/add-wire-addon.js

@@ -87,8 +87,7 @@ export function addWireAddon(node, state, logger) {
     if (!ts.isCallExpression(node))
         return;
     const { expression, arguments: args } = node;
-    if (!ts.isIdentifier(expression) ||
-        expression.text !== 'wireAddon')
+    if (!ts.isIdentifier(expression) || expression.text !== 'wireAddon')
         return;
     const [firstArg] = args;
     if (!firstArg || !ts.isObjectLiteralExpression(firstArg))
@@ -114,6 +113,7 @@ export function addWireAddon(node, state, logger) {
     let contentBucket;
     let contentGrants;
     let globalContent;
+    let contributors;
     for (const prop of firstArg.properties) {
         if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
             continue;
@@ -217,6 +217,14 @@ export function addWireAddon(node, state, logger) {
             ts.isObjectLiteralExpression(prop.initializer)) {
             contentGrants = parseStringRecord(prop.initializer);
         }
+        else if (key === 'contributors') {
+            contributors = parseStringArray(prop.initializer);
+            // An unreadable list read as "none" would silently drop services the
+            // project asked for.
+            if (contributors === undefined) {
+                logger.critical(ErrorCode.ADDON_CONTRIBUTORS_NOT_STATIC, `wireAddon's contributors must be an array of string literals, got: ${prop.initializer.getText()}`);
+            }
+        }
         else if (key === 'globalContent') {
             globalContent = ts.isStringLiteral(prop.initializer)
                 ? prop.initializer.text
@@ -248,6 +256,7 @@ export function addWireAddon(node, state, logger) {
         contentBucket,
         contentGrants,
         globalContent,
+        ...(contributors ? { contributors } : {}),
     });
     state.rpc.usedAddons.add(name);
     state.rpc.wireAddonFiles.add(node.getSourceFile().fileName);

package/dist/error-codes.d.ts

@@ -52,6 +52,12 @@ export declare enum ErrorCode {
     STUDIO_SCREEN_PATH_DUPLICATE = "PKU357",
     STUDIO_MESSAGE_KEY_MISSING = "PKU358",
     STUDIO_BADGE_FUNCTION_NOT_FOUND = "PKU359",
+    CONTRIBUTORS_NOT_STATIC = "PKU360",
+    CONTRIBUTOR_NAME_DUPLICATED = "PKU361",
+    ADDON_CONTRIBUTORS_NOT_STATIC = "PKU362",
+    ADDON_CONTRIBUTOR_UNKNOWN = "PKU363",
+    ADDON_LEGACY_CONTRIBUTORS = "PKU364",
+    STUDIO_SCREEN_AGENT_INVALID = "PKU365",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",

package/dist/error-codes.js

@@ -55,6 +55,12 @@ export var ErrorCode;
     ErrorCode["STUDIO_SCREEN_PATH_DUPLICATE"] = "PKU357";
     ErrorCode["STUDIO_MESSAGE_KEY_MISSING"] = "PKU358";
     ErrorCode["STUDIO_BADGE_FUNCTION_NOT_FOUND"] = "PKU359";
+    ErrorCode["CONTRIBUTORS_NOT_STATIC"] = "PKU360";
+    ErrorCode["CONTRIBUTOR_NAME_DUPLICATED"] = "PKU361";
+    ErrorCode["ADDON_CONTRIBUTORS_NOT_STATIC"] = "PKU362";
+    ErrorCode["ADDON_CONTRIBUTOR_UNKNOWN"] = "PKU363";
+    ErrorCode["ADDON_LEGACY_CONTRIBUTORS"] = "PKU364";
+    ErrorCode["STUDIO_SCREEN_AGENT_INVALID"] = "PKU365";
     // Database schema codegen warnings
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { inspect, analyzeProgram } from './inspector.js';
 export { getInitialInspectorState } from './initial-state.js';
 export { finalizeInspectorState } from './finalize.js';
 export type { TypesMap } from './types-map.js';
-export type { AddonConfig, AuthDefinition, CredentialOverrideMeta, StudioMeta, StudioScreenMeta, StudioNavMeta, AddonContributorRef, AddonContributorsMeta, InspectorDiagnostic, InspectorFilters, InspectorHTTPState, InspectorLogger, InspectorMiddlewareState, InspectorOptions, InspectorPermissionState, InspectorServiceTypes, InspectorState, MetaInputTypes, MiddlewareGroupMeta, MiddlewareRegistration, SchemaRef, } from './types.js';
+export type { AddonConfig, AuthDefinition, CredentialOverrideMeta, StudioMeta, StudioScreenMeta, StudioNavMeta, ContributorRef, ContributorVariantsMeta, ContributorsManifestMeta, OptedInContributorsMeta, InspectorDiagnostic, InspectorFilters, InspectorHTTPState, InspectorLogger, InspectorMiddlewareState, InspectorOptions, InspectorPermissionState, InspectorServiceTypes, InspectorState, MetaInputTypes, MiddlewareGroupMeta, MiddlewareRegistration, SchemaRef, } from './types.js';
 export type { FilesAndMethodsErrors } from './utils/get-files-and-methods.js';
 export { ErrorCode } from './error-codes.js';
 export type { DiagnosticSeverity, CodedDiagnostic } from './error-codes.js';

package/dist/types.d.ts

@@ -531,14 +531,14 @@ export type CredentialOverrideMeta = string | {
     name?: string;
     mode?: 'singleton' | 'wire';
 };
-/** A screen's nav entry as `pikkuStudio` declares it, read statically. */
+/** A screen's nav entry as `definePlugin` declares it, read statically. */
 export type StudioNavMeta = {
     area: 'rail' | 'team' | 'project' | 'account';
     icon: string;
     order: number;
     badge?: string;
 };
-/** A screen of an addon as `pikkuStudio` declares it, read statically. */
+/** A screen of an addon as `definePlugin` declares it, read statically. */
 export type StudioScreenMeta = {
     path: string;
     title: string;
@@ -548,6 +548,11 @@ export type StudioScreenMeta = {
     needsApp?: boolean;
     layout?: 'bare';
     scopes?: string[];
+    agent?: string;
+    /** Message key from the agent file's frontmatter, filled by validation. */
+    agentTitle?: string;
+    /** Message key from the agent file's frontmatter, filled by validation. */
+    agentDescription?: string;
 } & ({
     component: string;
     app?: undefined;
@@ -557,17 +562,40 @@ export type StudioScreenMeta = {
 });
 export type StudioMeta = {
     title: string;
-    /** The source file whose `pikkuStudio` call declared this manifest. */
+    /** The source file whose `definePlugin` call declared this manifest. */
     file: string;
     screens: StudioScreenMeta[];
     /**
      * The addon's role: every scope its own functions require, derived by
-     * `pikku all` and never declared. Absent from the raw `pikkuStudio` read.
+     * `pikku all` and never declared. Absent from the raw `definePlugin` read.
      * On a wired instance it also carries the host's `wireAddon` scopes, which
      * the runner demands of every function in the package.
      */
     scopes?: string[];
 };
+/**
+ * Where a contributor variant lives, so a host can import only that variant.
+ * `module` is the source file that declares it (absolute while it is in
+ * inspector state, relative to the addon package in the published meta);
+ * `export` is the name that module exports it under.
+ */
+export type ContributorRef = {
+    module: string;
+    export: string;
+};
+/** One `defineContributors` entry: each variant optional, each its own import. */
+export type ContributorVariantsMeta = {
+    dev?: ContributorRef;
+    deploy?: ContributorRef;
+};
+/** The contributors an addon registers, keyed by name. */
+export type ContributorsManifestMeta = Record<string, ContributorVariantsMeta>;
+/** The contributors a project opted in to for one wired addon. */
+export type OptedInContributorsMeta = {
+    packageName: string;
+    /** Each opted-in name with the variants the addon recorded; `module` is relative to the addon package. */
+    contributors: ContributorsManifestMeta;
+};
 export interface InspectorServiceTypes {
     /** Property names of the project's SingletonServices type, sorted. */
     singletonServices: string[] | null;
@@ -576,26 +604,15 @@ export interface InspectorServiceTypes {
     /** Singleton services that are a `SecretService` under another name. */
     secretAliases: string[];
 }
-export interface AddonContributorRef {
-    module: string;
-    export?: string;
-}
-export interface AddonContributorsMeta {
-    packageName: string;
-    packageDir: string;
-    contributors: AddonContributorRef[];
-}
 export interface InspectorState {
-    /** Set when this package calls `pikkuStudio`: the screens it ships. */
+    /** Set when this package calls `definePlugin`: the screens it ships. */
     studio?: StudioMeta;
-    /** The `pikkuStudio` metadata of the addons this project wires with `ui: true`, by namespace. */
+    /** The `definePlugin` metadata of the addons this project wires with `ui: true`, by namespace. */
     addonStudio?: Record<string, StudioMeta>;
-    /**
-     * Platform service contributors each wired, non-remote addon declares in its
-     * `package.json` under `pikku.contributors`, by namespace. `module` resolves
-     * from `packageDir`.
-     */
-    addonContributors?: Record<string, AddonContributorsMeta>;
+    /** Set when this package calls `defineContributors`: the contributors it registers, by name. */
+    contributorsManifest?: ContributorsManifestMeta;
+    /** Per wired addon namespace, the contributors `wireAddon({ contributors })` opted in to. */
+    optedInContributors?: Record<string, OptedInContributorsMeta>;
     rootDir: string;
     singletonServicesTypeImportMap: PathToNameAndType;
     wireServicesTypeImportMap: PathToNameAndType;
@@ -793,6 +810,8 @@ export interface InspectorState {
              * `ContentService` instead of one scoped to its own folder.
              */
             globalContent?: string;
+            /** The addon contributor names this project opted in to, as `wireAddon({ contributors })` listed them. */
+            contributors?: string[];
         }>;
         wireAddonFiles: Set<string>;
     };

package/dist/utils/load-addon-functions-meta.d.ts

@@ -1,4 +1,4 @@
-import type { AddonContributorsMeta, InspectorState, InspectorLogger } from '../types.js';
+import type { InspectorState, InspectorLogger } from '../types.js';
 import type { WebhookSourcesMeta } from '@pikku/core/trigger';
 export declare const describeMissingAddonMeta: (namespace: string, packageName: string, dirs: string[], declFile?: string) => string;
 /**
@@ -8,13 +8,6 @@ export declare const describeMissingAddonMeta: (namespace: string, packageName:
  * Every source starts off: the app turns one on at runtime.
  */
 export declare const namespaceAddonWebhookSources: (sources: WebhookSourcesMeta, namespace: string) => WebhookSourcesMeta;
-/**
- * The platform service contributors an addon declares in its package.json,
- * `"pikku": { "contributors": [{ "module", "export" }] }` — the same shape as
- * `dev.contributors`. `wireAddon` has no place for them: a contributor emits
- * code into the host's entry, so it belongs to the package, not the wiring.
- */
-export declare const readAddonContributors: (dirs: string[], packageName: string) => Promise<AddonContributorsMeta | null>;
 export declare function loadAddonFunctionsMeta(logger: InspectorLogger, state: InspectorState): Promise<void>;
 /**
  * Load addon schemas into state.schemas. Called after generateAllSchemas

package/dist/utils/load-addon-functions-meta.js

@@ -172,41 +172,62 @@ const loadStudioMeta = async (require, packageName) => {
         return null;
     return JSON.parse(await readFile(path, 'utf-8'));
 };
-const isContributorRef = (value) => !!value &&
-    typeof value === 'object' &&
-    typeof value.module === 'string' &&
-    (value.export === undefined ||
-        typeof value.export === 'string');
+const loadContributorsManifest = async (require, packageName) => {
+    const path = resolveAddonMeta(require, packageName, 'contributors/pikku-contributors-meta');
+    if (!path)
+        return {};
+    const meta = JSON.parse(await readFile(path, 'utf-8'));
+    return (meta?.contributors ?? {});
+};
 /**
- * The platform service contributors an addon declares in its package.json,
- * `"pikku": { "contributors": [{ "module", "export" }] }` — the same shape as
- * `dev.contributors`. `wireAddon` has no place for them: a contributor emits
- * code into the host's entry, so it belongs to the package, not the wiring.
+ * Resolves `wireAddon({ contributors })` against what the addon registered.
+ * A name the addon does not register is an error rather than a skip: the
+ * project asked for a service and would otherwise build without it.
  */
-export const readAddonContributors = async (dirs, packageName) => {
-    const packageDir = findInstalledPackageDir(dirs, packageName);
-    if (!packageDir)
-        return null;
-    let declared;
+const recordOptedInContributors = async (logger, state, require, namespace, packageName, names) => {
+    let registered;
     try {
-        const pkg = JSON.parse(await readFile(join(packageDir, 'package.json'), 'utf-8'));
-        declared = pkg?.pikku?.contributors;
+        registered = await loadContributorsManifest(require, packageName);
     }
-    catch {
-        return null;
+    catch (e) {
+        logger.critical(ErrorCode.ADDON_CONTRIBUTOR_UNKNOWN, `wireAddon('${namespace}') opts in to contributors, but the contributors manifest of ${packageName} could not be read: ${e instanceof Error ? e.message : e}`);
+        return;
     }
-    if (declared === undefined)
-        return null;
-    if (!Array.isArray(declared) || !declared.every(isContributorRef)) {
-        throw new Error(`${packageName} declares pikku.contributors in its package.json, but it is not a list of { module, export? }.`);
+    const selected = {};
+    for (const name of names) {
+        if (!Object.hasOwn(registered, name)) {
+            const known = Object.keys(registered);
+            logger.critical(ErrorCode.ADDON_CONTRIBUTOR_UNKNOWN, `wireAddon('${namespace}') opts in to contributor '${name}', but ${packageName} registers no such contributor. ${known.length > 0
+                ? `It registers: ${known.join(', ')}.`
+                : 'It registers none; add a defineContributors call to the package and run pikku all in it.'}`);
+            continue;
+        }
+        selected[name] = registered[name];
+    }
+    if (Object.keys(selected).length > 0) {
+        ;
+        (state.optedInContributors ??= {})[namespace] = {
+            packageName,
+            contributors: selected,
+        };
+    }
+};
+/**
+ * `pikku.contributors` in an addon's package.json was the string-emitting
+ * contributor route. It is no longer read, so it is reported rather than left
+ * to stop applying silently.
+ */
+const hasLegacyContributors = async (dirs, packageName) => {
+    const dir = findInstalledPackageDir(dirs, packageName);
+    if (!dir)
+        return false;
+    try {
+        const pkg = JSON.parse(await readFile(join(dir, 'package.json'), 'utf-8'));
+        return pkg?.pikku?.contributors !== undefined;
+    }
+    catch {
+        return false;
     }
-    if (declared.length === 0)
-        return null;
-    return {
-        packageName,
-        packageDir,
-        contributors: declared.map(({ module, export: name }) => name === undefined ? { module } : { module, export: name }),
-    };
 };
 /**
  * A versioned remote addon's function metadata comes from the SDK `pikku addon
@@ -275,17 +296,13 @@ export async function loadAddonFunctionsMeta(logger, state) {
         const dirs = addonResolutionDirs(state.rootDir, decl.file);
         const require = createAddonResolver(dirs);
         try {
-            try {
-                const contributors = await readAddonContributors(dirs, decl.package);
-                if (contributors) {
-                    ;
-                    (state.addonContributors ??= {})[namespace] = contributors;
-                }
+            recordDeclaredUses(logger, namespace, decl, dirs);
+            if (decl.contributors && decl.contributors.length > 0) {
+                await recordOptedInContributors(logger, state, require, namespace, decl.package, decl.contributors);
             }
-            catch (error) {
-                logger.error(`wireAddon('${namespace}'): ${error instanceof Error ? error.message : error}`);
+            if (await hasLegacyContributors(dirs, decl.package)) {
+                logger.critical(ErrorCode.ADDON_LEGACY_CONTRIBUTORS, `${decl.package} still declares "pikku.contributors" in its package.json, which is no longer read. Remove it, register the contributors with defineContributors in the addon's source, and opt in with wireAddon('${namespace}', { contributors: [...] }). See docs/contributors.md.`);
             }
-            recordDeclaredUses(logger, namespace, decl, dirs);
             if (decl.ui) {
                 let manifest;
                 let unreadable = false;
@@ -300,7 +317,7 @@ export async function loadAddonFunctionsMeta(logger, state) {
                     // reported above; the addon's functions and scopes still load
                 }
                 else if (!manifest || manifest.screens.length === 0) {
-                    logger.critical(ErrorCode.ADDON_UI_HAS_NO_SCREENS, `wireAddon('${namespace}') sets ui: true, but ${decl.package} declares no screens. Add a pikkuStudio call to the package, or drop ui.`);
+                    logger.critical(ErrorCode.ADDON_UI_HAS_NO_SCREENS, `wireAddon('${namespace}') sets ui: true, but ${decl.package} declares no screens. Add a definePlugin call to the package, or drop ui.`);
                 }
                 else {
                     ;

package/dist/utils/serialize-inspector-state.d.ts

@@ -212,6 +212,7 @@ export interface SerializableInspectorState {
                 contentBucket?: string;
                 contentGrants?: Record<string, string>;
                 globalContent?: string;
+                contributors?: string[];
             }
         ]>;
         wireAddonFiles: string[];
@@ -331,7 +332,8 @@ export interface SerializableInspectorState {
     remoteAddonFunctions?: InspectorState['remoteAddonFunctions'];
     studio?: InspectorState['studio'];
     addonStudio?: InspectorState['addonStudio'];
-    addonContributors?: InspectorState['addonContributors'];
+    contributorsManifest?: InspectorState['contributorsManifest'];
+    optedInContributors?: InspectorState['optedInContributors'];
     exportedContracts: InspectorState['exportedContracts'];
 }
 /**

package/dist/utils/serialize-inspector-state.js

@@ -196,7 +196,8 @@ export function serializeInspectorState(state) {
         remoteAddonFunctions: state.remoteAddonFunctions,
         studio: state.studio,
         addonStudio: state.addonStudio,
-        addonContributors: state.addonContributors,
+        contributorsManifest: state.contributorsManifest,
+        optedInContributors: state.optedInContributors,
         exportedContracts: state.exportedContracts,
     };
 }
@@ -406,7 +407,8 @@ export function deserializeInspectorState(data) {
             : {}),
         studio: data.studio,
         addonStudio: data.addonStudio,
-        addonContributors: data.addonContributors,
+        contributorsManifest: data.contributorsManifest,
+        optedInContributors: data.optedInContributors,
         exportedContracts: data.exportedContracts || {
             http: {},
             cli: {},

package/dist/visit.js

@@ -16,6 +16,7 @@ import { addGateway } from './add/add-gateway.js';
 import { addRPCInvocations } from './add/add-rpc-invocations.js';
 import { addWireAddon } from './add/add-wire-addon.js';
 import { addPikkuStudio } from './add/add-pikku-studio.js';
+import { addDefineContributors } from './add/add-define-contributors.js';
 import { addWireRemoteAddon } from './add/add-wire-remote-addon.js';
 import { addMiddleware } from './add/add-middleware.js';
 import { addPermission } from './add/add-permission.js';
@@ -52,6 +53,7 @@ export const visitSetup = (logger, checker, node, state, options) => {
     addRPCInvocations(node, state, logger);
     addWireAddon(node, state, logger);
     addPikkuStudio(node, state, logger);
+    addDefineContributors(logger, node, checker, state);
     addWireRemoteAddon(node, state, logger);
     addMiddleware(logger, node, checker, state, options);
     addPermission(logger, node, checker, state, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.111",
+  "version": "0.12.113",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -70,10 +70,10 @@
     "zod": "^4.6.7"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.147"
+    "@pikku/core": "^0.12.150"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.147",
+    "@pikku/core": "^0.12.150",
     "@types/node": "^26.6.5"
   },
   "engines": {