@pikku/inspector 0.12.110 → 0.12.111

package/dist/add/check-disabled-references.js

@@ -0,0 +1,226 @@
+import * as ts from 'typescript';
+import { relative } from 'node:path';
+import { ErrorCode } from '../error-codes.js';
+/**
+ * A function's `disabled`, read from its config: `true`, or a non-empty string
+ * saying why. Anything else the build cannot read statically is refused rather
+ * than taken as enabled.
+ */
+export const readFunctionDisabled = (obj, name, logger) => {
+    for (const prop of obj.properties) {
+        if (!ts.isPropertyAssignment(prop) ||
+            !ts.isIdentifier(prop.name) ||
+            prop.name.text !== 'disabled') {
+            continue;
+        }
+        const init = prop.initializer;
+        if (init.kind === ts.SyntaxKind.TrueKeyword)
+            return {};
+        if (init.kind === ts.SyntaxKind.FalseKeyword)
+            return null;
+        if ((ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init)) &&
+            init.text !== '') {
+            return { reason: init.text };
+        }
+        logger.critical(ErrorCode.INVALID_VALUE, `'${name}' has a \`disabled\` the build cannot read. Use \`true\` or a non-empty string literal.`);
+        return {};
+    }
+    return null;
+};
+const describe = (state, meta) => `'${meta.name}' is disabled${meta.reason ? ` (${meta.reason})` : ''} in ${relative(state.rootDir, meta.sourceFile)}`;
+const position = (state, node) => {
+    const sourceFile = node.getSourceFile();
+    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+    return `${relative(state.rootDir, sourceFile.fileName)}:${line + 1}`;
+};
+/** The call a reference sits in, by its callee: `wireHTTP`, `rpc.invoke`. */
+const enclosingCall = (node) => {
+    for (let current = node.parent; current; current = current.parent) {
+        if (ts.isCallExpression(current) &&
+            (ts.isIdentifier(current.expression) ||
+                ts.isPropertyAccessExpression(current.expression))) {
+            return current.expression.getText();
+        }
+    }
+    return undefined;
+};
+/**
+ * Records a function declared with `disabled`, in place of everything
+ * addFunctions would otherwise record. A function defined inline in what
+ * uses it is referenced by that, so it is refused instead.
+ */
+export const recordDisabledFunction = (logger, state, node, pikkuFuncId, meta) => {
+    const parent = node.parent;
+    if (ts.isVariableDeclaration(parent) && parent.initializer === node) {
+        state.functions.disabled[pikkuFuncId] = meta;
+        return;
+    }
+    const call = enclosingCall(node);
+    logger.critical(ErrorCode.DISABLED_FUNCTION_REFERENCED, `A function declared \`disabled\` is defined inline at ${position(state, node)}` +
+        (call ? ` inside ${call}(...)` : '') +
+        `, which still uses it. Remove what uses it, or remove \`disabled\`.`);
+};
+const byLocalName = new WeakMap();
+/** Disabled functions by the name code reaches them by: the export, else the name. */
+const disabledByLocalName = (state) => {
+    let index = byLocalName.get(state);
+    if (index)
+        return index;
+    index = new Map();
+    for (const meta of Object.values(state.functions.disabled)) {
+        const local = meta.exportedName ?? meta.name;
+        index.set(local, [...(index.get(local) ?? []), meta]);
+    }
+    byLocalName.set(state, index);
+    return index;
+};
+/** Whether a node is inside the definition of a disabled function, whose body is dead too. */
+const isInsideDisabled = (state, node) => {
+    const fileName = node.getSourceFile().fileName;
+    const index = disabledByLocalName(state);
+    for (let current = node.parent; current; current = current.parent) {
+        if (ts.isVariableDeclaration(current) &&
+            ts.isIdentifier(current.name) &&
+            index.get(current.name.text)?.some((meta) => meta.sourceFile === fileName)) {
+            return true;
+        }
+    }
+    return false;
+};
+const isNotAReference = (node) => {
+    const parent = node.parent;
+    if (ts.isImportSpecifier(parent) ||
+        ts.isExportSpecifier(parent) ||
+        ts.isImportClause(parent) ||
+        ts.isNamespaceImport(parent) ||
+        ts.isTypeQueryNode(parent) ||
+        ts.isQualifiedName(parent)) {
+        return true;
+    }
+    if (ts.isShorthandPropertyAssignment(parent))
+        return false;
+    return 'name' in parent && parent.name === node;
+};
+const resolveDeclaration = (node, checker) => {
+    let symbol = ts.isShorthandPropertyAssignment(node.parent)
+        ? checker.getShorthandAssignmentValueSymbol(node.parent)
+        : checker.getSymbolAtLocation(node);
+    if (symbol && symbol.flags & ts.SymbolFlags.Alias) {
+        symbol = checker.getAliasedSymbol(symbol);
+    }
+    return symbol?.valueDeclaration ?? symbol?.declarations?.[0];
+};
+/** `rpc.invoke('x')` / `rpc.mesh('x')`, seen through `!` and parentheses. */
+const invokedRpcName = (node) => {
+    const callee = node.expression;
+    if (!ts.isPropertyAccessExpression(callee) ||
+        (callee.name.text !== 'invoke' && callee.name.text !== 'mesh')) {
+        return undefined;
+    }
+    let receiver = callee.expression;
+    while (ts.isNonNullExpression(receiver) ||
+        ts.isParenthesizedExpression(receiver)) {
+        receiver = receiver.expression;
+    }
+    const isRpc = ts.isIdentifier(receiver)
+        ? receiver.text === 'rpc'
+        : ts.isPropertyAccessExpression(receiver) && receiver.name.text === 'rpc';
+    const [first] = node.arguments;
+    if (!isRpc ||
+        !first ||
+        !(ts.isStringLiteral(first) || ts.isNoSubstitutionTemplateLiteral(first))) {
+        return undefined;
+    }
+    return first.text;
+};
+/**
+ * Whether a node sits in a generated file. This run rewrites those from its own
+ * state, which leaves disabled functions out, so a reference there is the last
+ * run's and is about to go.
+ */
+const isGenerated = (node) => {
+    const fileName = node.getSourceFile().fileName;
+    return fileName.endsWith('.gen.ts') || fileName.endsWith('.gen.js');
+};
+/**
+ * PKU562: anything that still references a disabled function — a wiring, an
+ * agent's tools, an `rpc.invoke` by name, any other code. Runs in the routes
+ * sweep, after every function is registered, so it sees the whole set.
+ */
+export const checkDisabledReferences = (logger, node, checker, state) => {
+    if (Object.keys(state.functions.disabled).length === 0)
+        return;
+    if (isGenerated(node))
+        return;
+    if (ts.isCallExpression(node)) {
+        const invoked = invokedRpcName(node);
+        if (invoked === undefined)
+            return;
+        const meta = Object.values(state.functions.disabled).find((m) => m.name === invoked);
+        if (!meta || isInsideDisabled(state, node))
+            return;
+        logger.critical(ErrorCode.DISABLED_FUNCTION_REFERENCED, `${describe(state, meta)}, but ${node.expression.getText()}('${invoked}') calls it at ${position(state, node)}. ` +
+            `Remove the call, or remove \`disabled\`.`);
+        return;
+    }
+    if (!ts.isIdentifier(node))
+        return;
+    const candidates = disabledByLocalName(state).get(node.text);
+    if (!candidates || isNotAReference(node))
+        return;
+    const decl = resolveDeclaration(node, checker);
+    if (!decl || !ts.isVariableDeclaration(decl) || !ts.isIdentifier(decl.name)) {
+        return;
+    }
+    const declFile = decl.getSourceFile().fileName;
+    const declName = decl.name.text;
+    const meta = candidates.find((m) => m.sourceFile === declFile && (m.exportedName ?? m.name) === declName);
+    if (!meta || isInsideDisabled(state, node))
+        return;
+    const call = enclosingCall(node);
+    logger.critical(ErrorCode.DISABLED_FUNCTION_REFERENCED, `${describe(state, meta)}, but ` +
+        (call ? `${call}(...) references it` : 'it is referenced') +
+        ` at ${position(state, node)}. Remove the reference, or remove \`disabled\`.`);
+};
+/** Every `rpcName` in a workflow's meta, wherever in its steps it sits. */
+const collectRpcNames = (value, into) => {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectRpcNames(item, into);
+        return;
+    }
+    if (!value || typeof value !== 'object')
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if (key === 'rpcName' && typeof child === 'string')
+            into.add(child);
+        else
+            collectRpcNames(child, into);
+    }
+};
+/**
+ * PKU562 for workflow steps, which name the function they call as a string
+ * the workflow meta already holds. Runs once, after the routes sweep.
+ */
+export const checkDisabledWorkflowSteps = (logger, state) => {
+    const disabled = Object.values(state.functions.disabled);
+    if (disabled.length === 0)
+        return;
+    const sections = [
+        ['workflow', state.workflows.meta],
+        ['workflow graph', state.workflows.graphMeta],
+    ];
+    for (const [kind, section] of sections) {
+        for (const [workflowName, meta] of Object.entries(section)) {
+            const names = new Set();
+            collectRpcNames(meta, names);
+            for (const rpcName of [...names].sort()) {
+                const target = disabled.find((m) => m.name === rpcName);
+                if (!target)
+                    continue;
+                logger.critical(ErrorCode.DISABLED_FUNCTION_REFERENCED, `${describe(state, target)}, but ${kind} '${workflowName}' calls it as a step. ` +
+                    `Remove the step, or remove \`disabled\`.`);
+            }
+        }
+    }
+};

package/dist/error-codes.d.ts

@@ -46,6 +46,12 @@ export declare enum ErrorCode {
     REMOTE_ADDON_SDK_CORE_MISMATCH = "PKU351",
     REMOTE_ADDON_SDK_INTEGRITY_MISMATCH = "PKU352",
     REMOTE_ADDON_PACKAGE_INVALID = "PKU353",
+    ADDON_DEPENDENCY_VERSION_MISMATCH = "PKU354",
+    ADDON_USES_NOT_DECLARED = "PKU355",
+    ADDON_DEPENDENCY_INVALID = "PKU356",
+    STUDIO_SCREEN_PATH_DUPLICATE = "PKU357",
+    STUDIO_MESSAGE_KEY_MISSING = "PKU358",
+    STUDIO_BADGE_FUNCTION_NOT_FOUND = "PKU359",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",
@@ -56,6 +62,9 @@ export declare enum ErrorCode {
     SCHEMA_REFERENCE_UNRESOLVED = "PKU463",
     INLINE_SCHEMA = "PKU489",
     FUNCTION_METADATA_NOT_FOUND = "PKU559",
+    DISABLED_FUNCTION_REFERENCED = "PKU562",
+    UNUSED_FUNCTION = "PKU563",
+    FACTORY_NOT_A_DIRECT_CALL = "PKU564",
     DUPLICATE_AUTH_DEFINITION = "PKU581",
     AUTH_NOT_EXPORTED = "PKU582",
     DUPLICATE_VIRTUAL_USERS_DEFINITION = "PKU585",

package/dist/error-codes.js

@@ -49,6 +49,12 @@ export var ErrorCode;
     ErrorCode["REMOTE_ADDON_SDK_CORE_MISMATCH"] = "PKU351";
     ErrorCode["REMOTE_ADDON_SDK_INTEGRITY_MISMATCH"] = "PKU352";
     ErrorCode["REMOTE_ADDON_PACKAGE_INVALID"] = "PKU353";
+    ErrorCode["ADDON_DEPENDENCY_VERSION_MISMATCH"] = "PKU354";
+    ErrorCode["ADDON_USES_NOT_DECLARED"] = "PKU355";
+    ErrorCode["ADDON_DEPENDENCY_INVALID"] = "PKU356";
+    ErrorCode["STUDIO_SCREEN_PATH_DUPLICATE"] = "PKU357";
+    ErrorCode["STUDIO_MESSAGE_KEY_MISSING"] = "PKU358";
+    ErrorCode["STUDIO_BADGE_FUNCTION_NOT_FOUND"] = "PKU359";
     // Database schema codegen warnings
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";
@@ -62,6 +68,9 @@ export var ErrorCode;
     ErrorCode["INLINE_SCHEMA"] = "PKU489";
     // Function errors
     ErrorCode["FUNCTION_METADATA_NOT_FOUND"] = "PKU559";
+    ErrorCode["DISABLED_FUNCTION_REFERENCED"] = "PKU562";
+    ErrorCode["UNUSED_FUNCTION"] = "PKU563";
+    ErrorCode["FACTORY_NOT_A_DIRECT_CALL"] = "PKU564";
     // Auth errors
     ErrorCode["DUPLICATE_AUTH_DEFINITION"] = "PKU581";
     ErrorCode["AUTH_NOT_EXPORTED"] = "PKU582";

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, ScreensManifestMeta, AddonScreenMeta, 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, AddonContributorRef, AddonContributorsMeta, 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';
@@ -16,6 +16,7 @@ export { incompatibleServicesFor, resolveDeployTarget, } from './utils/resolve-d
 export { generateCustomTypes, customTypeNames, sanitizeTypeName, } from './utils/custom-types-generator.js';
 export type { GenerateCustomTypesOptions } from './utils/custom-types-generator.js';
 export { unresolvedSchemaReferences } from './utils/post-process.js';
+export { findUnusedFunctions, type UnusedFunction, } from './utils/find-unused-functions.js';
 export type { SurfaceUsageCounts } from './utils/extract-surface-usage.js';
 export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
 export type { ContractEntry, VersionHashEntry, VersionValidateError, VersionManifest, VersionManifestEntry, } from './utils/contract-hashes.js';

package/dist/index.js

@@ -9,6 +9,7 @@ export { filterInspectorState } from './utils/filter-inspector-state.js';
 export { incompatibleServicesFor, resolveDeployTarget, } from './utils/resolve-deploy-target.js';
 export { generateCustomTypes, customTypeNames, sanitizeTypeName, } from './utils/custom-types-generator.js';
 export { unresolvedSchemaReferences } from './utils/post-process.js';
+export { findUnusedFunctions, } from './utils/find-unused-functions.js';
 export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
 export { serializeMCPJson } from './utils/serialize-mcp-json.js';
 export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/deserialize-dsl-workflow.js';

package/dist/initial-state.js

@@ -31,6 +31,7 @@ export function getInitialInspectorState(rootDir) {
             files: new Map(),
             approvalDescriptions: {},
             dynamicImportIds: new Set(),
+            disabled: {},
         },
         http: {
             metaInputTypes: new Map(),

package/dist/inspector.js

@@ -8,6 +8,7 @@ import { createNestedProjectFilter } from './utils/nested-project-filter.js';
 import { toProgramPath } from './utils/program-path.js';
 import { resolveLatestVersions } from './utils/resolve-versions.js';
 import { validateWebhookSourceTriggers } from './add/add-trigger.js';
+import { validatePikkuStudio } from './add/add-pikku-studio.js';
 import { generateAllSchemas } from './utils/schema-generator.js';
 import { extractSecretUsage } from './utils/extract-secret-usage.js';
 import { accumulateSurfaceUsage, surfaceUsageArea, } from './utils/extract-surface-usage.js';
@@ -15,6 +16,7 @@ import { loadAddonFunctionsMeta } from './utils/load-addon-functions-meta.js';
 import { resolveServiceTypes } from './utils/resolve-service-types.js';
 import { finalizeInspectorState } from './finalize.js';
 import { getInitialInspectorState } from './initial-state.js';
+import { checkDisabledWorkflowSteps } from './add/check-disabled-references.js';
 export { getInitialInspectorState };
 /**
  * The path mappings the inspector's program has to share with the project.
@@ -140,7 +142,9 @@ export const analyzeProgram = async (logger, routeFiles, options = {}) => {
             ts.forEachChild(sourceFile, (child) => visitRoutes(logger, checker, child, state, sourceOptions));
         }
         logger.debug(`Visit routes phase completed in ${(performance.now() - startRoutes).toFixed(0)}ms`);
+        checkDisabledWorkflowSteps(logger, state);
         validateWebhookSourceTriggers(logger, state);
+        validatePikkuStudio(logger, state);
         resolveLatestVersions(state, logger);
         if (options.schemaConfig) {
             const startSchemas = performance.now();

package/dist/lite.d.ts

@@ -19,6 +19,7 @@ export { filterInspectorState } from './utils/filter-inspector-state.js';
 export { incompatibleServicesFor, resolveDeployTarget, } from './utils/resolve-deploy-target.js';
 export { customTypeNames, generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
 export { unresolvedSchemaReferences } from './utils/post-process.js';
+export { findUnusedFunctions, type UnusedFunction, } from './utils/find-unused-functions.js';
 export { computeContractHash, createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
 export { serializeMCPJson } from './utils/serialize-mcp-json.js';
 export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/deserialize-dsl-workflow.js';
@@ -27,3 +28,5 @@ export { resolveCoreType } from './utils/resolve-core-type.js';
 export { addonResolutionDirs, createAddonResolver, } from './utils/addon-resolution.js';
 export { ADDONS_LOCK_FILE, REMOTE_SDK_DIR, SDK_INTEGRITY_MARKER, checkLockedSdk, emptyAddonsLock, parseRemoteAddonPackage, readAddonsLock, readSdkManifest, remoteSdkDir, serializeAddonsLock, } from './utils/remote-addon-sdk.js';
 export type { AddonsLock, AddonsLockEntry, RemoteAddonSdkManifest, RemoteAddonPackageSpec, LockedSdk, } from './utils/remote-addon-sdk.js';
+export { declaredAddonNames, findInstalledPackageDir, parseAddonDependencies, readAddonDependencies, } from './utils/addon-dependencies.js';
+export type { AddonDependency, AddonDependencies, } from './utils/addon-dependencies.js';

package/dist/lite.js

@@ -18,6 +18,7 @@ export { filterInspectorState } from './utils/filter-inspector-state.js';
 export { incompatibleServicesFor, resolveDeployTarget, } from './utils/resolve-deploy-target.js';
 export { customTypeNames, generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
 export { unresolvedSchemaReferences } from './utils/post-process.js';
+export { findUnusedFunctions, } from './utils/find-unused-functions.js';
 export { computeContractHash, createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
 export { serializeMCPJson } from './utils/serialize-mcp-json.js';
 export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/deserialize-dsl-workflow.js';
@@ -25,3 +26,4 @@ export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
 export { resolveCoreType } from './utils/resolve-core-type.js';
 export { addonResolutionDirs, createAddonResolver, } from './utils/addon-resolution.js';
 export { ADDONS_LOCK_FILE, REMOTE_SDK_DIR, SDK_INTEGRITY_MARKER, checkLockedSdk, emptyAddonsLock, parseRemoteAddonPackage, readAddonsLock, readSdkManifest, remoteSdkDir, serializeAddonsLock, } from './utils/remote-addon-sdk.js';
+export { declaredAddonNames, findInstalledPackageDir, parseAddonDependencies, readAddonDependencies, } from './utils/addon-dependencies.js';

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type * as ts from 'typescript';
 import type { SecretUsage } from './utils/extract-secret-usage.js';
+import type { AddonDependency } from './utils/addon-dependencies.js';
 import type { SurfaceUsageCounts } from './utils/extract-surface-usage.js';
 import type { ChannelMessageMeta, ChannelsMeta } from '@pikku/core/channel';
 import type { GatewaysMeta } from '@pikku/core/gateway';
@@ -105,6 +106,19 @@ export interface InspectorFunctionState {
      * inspection pass — deliberately not part of the serialized function meta.
      */
     dynamicImportIds: Set<string>;
+    /**
+     * Functions declared with `disabled`, keyed by pikkuFuncId. They are in no
+     * other part of the state: nothing is generated for them, and a reference
+     * to one is PKU562.
+     */
+    disabled: Record<string, DisabledFunctionMeta>;
+}
+export interface DisabledFunctionMeta {
+    name: string;
+    sourceFile: string;
+    exportedName?: string;
+    /** The string `disabled` was given, when it was not just `true`. */
+    reason?: string;
 }
 export interface InspectorChannelState {
     meta: ChannelsMeta;
@@ -517,11 +531,22 @@ export type CredentialOverrideMeta = string | {
     name?: string;
     mode?: 'singleton' | 'wire';
 };
-/** A screen of an addon as `defineScreens` declares it, read statically. */
-export type AddonScreenMeta = {
+/** A screen's nav entry as `pikkuStudio` 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. */
+export type StudioScreenMeta = {
     path: string;
     title: string;
-    nav?: boolean;
+    scope: 'studio' | 'team' | 'project';
+    nav?: StudioNavMeta;
+    replaces?: boolean;
+    needsApp?: boolean;
+    layout?: 'bare';
     scopes?: string[];
 } & ({
     component: string;
@@ -530,15 +555,14 @@ export type AddonScreenMeta = {
     app: string;
     component?: undefined;
 });
-export type ScreensManifestMeta = {
+export type StudioMeta = {
     title: string;
-    icon?: string;
-    /** The source file whose `defineScreens` call declared this manifest. */
+    /** The source file whose `pikkuStudio` call declared this manifest. */
     file: string;
-    screens: AddonScreenMeta[];
+    screens: StudioScreenMeta[];
     /**
      * The addon's role: every scope its own functions require, derived by
-     * `pikku all` and never declared. Absent from the raw `defineScreens` read.
+     * `pikku all` and never declared. Absent from the raw `pikkuStudio` read.
      * On a wired instance it also carries the host's `wireAddon` scopes, which
      * the runner demands of every function in the package.
      */
@@ -562,10 +586,10 @@ export interface AddonContributorsMeta {
     contributors: AddonContributorRef[];
 }
 export interface InspectorState {
-    /** Set when this package calls `defineScreens`: the screens it ships. */
-    screensManifest?: ScreensManifestMeta;
-    /** The screens of the addons this project wires with `ui: true`, by namespace. */
-    addonScreens?: Record<string, ScreensManifestMeta>;
+    /** Set when this package calls `pikkuStudio`: the screens it ships. */
+    studio?: StudioMeta;
+    /** The `pikkuStudio` 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
@@ -688,8 +712,20 @@ export interface InspectorState {
             /** Declared with `ui: true`: the package must ship screens, and the host mounts them. */
             ui?: boolean;
             rpcEndpoint?: string;
-            /** The other addons this instance may call: package -> the name it is wired under. */
+            /**
+             * The other addons this instance may call: the name the addon calls
+             * (its declared alias, or the package name) -> the name the target is
+             * wired under in this app.
+             */
             uses?: Record<string, string>;
+            /**
+             * The names the addon's package.json declares under `pikku.uses`, in
+             * either form. Read when its meta loads; absent when it declares
+             * nothing, which leaves `uses` unchecked against a declaration.
+             */
+            declaredUses?: string[];
+            /** The `{ alias: 'package@range' }` form of `pikku.uses`, per alias. */
+            dependencies?: AddonDependency[];
             /**
              * `true` offers every function the addon declared `mcp: true`; a list
              * names the functions to offer, whatever the addon declared. Absent

package/dist/utils/addon-dependencies.d.ts

@@ -0,0 +1,43 @@
+/**
+ * One addon an addon calls: the alias its code calls it by
+ * (`rpc.invoke('<alias>:<fn>')`) and the package and semver range it was
+ * written against.
+ */
+export type AddonDependency = {
+    alias: string;
+    package: string;
+    range: string;
+};
+/**
+ * What an addon's package.json declares under `pikku.uses`.
+ *
+ * - `none`: nothing. The wiring's `uses` is not checked against a declaration.
+ * - `list`: the older form, a list of names the addon calls. The name is also
+ *   the package the wiring must map it to.
+ * - `map`: `{ "<alias>": "<package>@<range>" }`. `invalid` holds a message for
+ *   each entry that could not be read; those entries are not in `dependencies`.
+ *
+ * knowledge: decisions/an-addon-declares-the-addons-it-calls.md
+ */
+export type AddonDependencies = {
+    form: 'none';
+} | {
+    form: 'list';
+    names: string[];
+} | {
+    form: 'map';
+    dependencies: AddonDependency[];
+    invalid: string[];
+};
+/** The names a wiring's `uses` may map: the declared aliases, or the listed names. */
+export declare const declaredAddonNames: (declared: AddonDependencies) => string[];
+/** Reads the `pikku.uses` value of an addon's package.json. */
+export declare const parseAddonDependencies: (uses: unknown) => AddonDependencies;
+/** The `pikku.uses` an addon's package.json declares. `none` when there is no readable package.json. */
+export declare const readAddonDependencies: (packageDir: string) => AddonDependencies;
+/**
+ * The directory `packageName` is installed in, looking in `node_modules` from
+ * each of `dirs` upwards, as Node's resolution would. Null when it is not
+ * installed.
+ */
+export declare const findInstalledPackageDir: (dirs: string[], packageName: string) => string | null;

package/dist/utils/addon-dependencies.js

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join, parse } from 'path';
+import { parseRemoteAddonPackage } from './remote-addon-sdk.js';
+/** An alias becomes a namespace prefix and part of a generated type name. */
+const ALIAS = /^[A-Za-z][A-Za-z0-9_-]*$/;
+/** The names a wiring's `uses` may map: the declared aliases, or the listed names. */
+export const declaredAddonNames = (declared) => declared.form === 'list'
+    ? declared.names
+    : declared.form === 'map'
+        ? declared.dependencies.map((d) => d.alias)
+        : [];
+/** Reads the `pikku.uses` value of an addon's package.json. */
+export const parseAddonDependencies = (uses) => {
+    if (uses === undefined || uses === null)
+        return { form: 'none' };
+    if (Array.isArray(uses)) {
+        return {
+            form: 'list',
+            names: uses.filter((u) => typeof u === 'string'),
+        };
+    }
+    if (typeof uses !== 'object') {
+        return {
+            form: 'map',
+            dependencies: [],
+            invalid: [
+                `pikku.uses must be an object of { "<alias>": "<package>@<range>" }, got ${JSON.stringify(uses)}.`,
+            ],
+        };
+    }
+    const dependencies = [];
+    const invalid = [];
+    for (const [alias, spec] of Object.entries(uses)) {
+        if (!ALIAS.test(alias)) {
+            invalid.push(`pikku.uses names '${alias}', which is not a valid alias. An alias starts with a letter and holds only letters, digits, '-' and '_'.`);
+            continue;
+        }
+        if (typeof spec !== 'string') {
+            invalid.push(`pikku.uses.${alias} must be a string '<package>@<range>', got ${JSON.stringify(spec)}.`);
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = parseRemoteAddonPackage(spec);
+        }
+        catch (e) {
+            invalid.push(`pikku.uses.${alias}: ${e instanceof Error ? e.message : String(e)}`);
+            continue;
+        }
+        if (!parsed.range) {
+            invalid.push(`pikku.uses.${alias} is '${spec}', which has no version range. Write '${parsed.name}@^1.0.0': the app that wires this addon is checked against it.`);
+            continue;
+        }
+        dependencies.push({ alias, package: parsed.name, range: parsed.range });
+    }
+    return { form: 'map', dependencies, invalid };
+};
+/** The `pikku.uses` an addon's package.json declares. `none` when there is no readable package.json. */
+export const readAddonDependencies = (packageDir) => {
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf-8'));
+    }
+    catch {
+        return { form: 'none' };
+    }
+    return parseAddonDependencies(pkg?.pikku?.uses);
+};
+/**
+ * The directory `packageName` is installed in, looking in `node_modules` from
+ * each of `dirs` upwards, as Node's resolution would. Null when it is not
+ * installed.
+ */
+export const findInstalledPackageDir = (dirs, packageName) => {
+    for (const start of dirs) {
+        const root = parse(start).root;
+        let dir = start;
+        while (dir) {
+            const candidate = join(dir, 'node_modules', packageName);
+            if (existsSync(join(candidate, 'package.json')))
+                return candidate;
+            if (dir === root)
+                break;
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return null;
+};

package/dist/utils/find-unused-functions.d.ts

@@ -0,0 +1,20 @@
+import type { InspectorState } from '../types.js';
+export interface UnusedFunction {
+    pikkuFuncId: string;
+    name?: string;
+    sourceFile?: string;
+}
+/**
+ * The app's own functions that nothing uses: not wired to any transport, not
+ * exposed, published or offered to MCP, and not called by name. Addon
+ * functions are never judged: an addon project's own functions are all addon
+ * functions, and a consumer's state holds no addon functions in
+ * `functions.meta`. Neither are scenarios, inline wiring functions or disabled
+ * functions. A workflow is a function like any other: it is used when it is
+ * wired, exposed, or started by a literal name — `rpc.startWorkflow`,
+ * `workflowService.startWorkflow` / `runToCompletion`, `rpc.invoke`, another
+ * workflow's step, or the generated client helpers.
+ */
+export declare const findUnusedFunctions: (state: InspectorState, { addon }?: {
+    addon?: boolean;
+}) => UnusedFunction[];