@pikku/inspector 0.12.101 → 0.12.103

package/CHANGELOG.md

@@ -1,3 +1,28 @@
+## 0.12.103
+
+### Patch Changes
+
+- 53ac40d: An addon can ship screens: `wireAddon({ ui: true })` mounts what the package declares with `defineScreens`, the inspector reads them, `pikku all` emits the screens manifest and the installed-addons registry, and `x-pikku-addon` narrows a session to the addon's role. `pikku new addon --ui` scaffolds one; its tables must be prefixed `<name>_`.
+- Updated dependencies [a196a21]
+- Updated dependencies [53ac40d]
+- Updated dependencies [443fd40]
+- Updated dependencies [56c8047]
+  - @pikku/core@0.12.139
+
+## 0.12.102
+
+### Patch Changes
+
+- 3c0b151: `pikku validate` checks block libraries. The project's `pikku.config.json` lists them by package name under `blocks`; each listed package's `src/blocks` is checked. A block that renders a literal string is an error, because its words have to come from messages, and a block with no `.stories.tsx` is a warning. A block with no errors is reported as productized. A listed name that matches no package, or a package with no `src/blocks`, is an error.
+- 0963b73: Every scope tree now records where it came from: `origin` on `ScopeDefinitionMeta` is `{ kind: 'app' }` for the app's own `defineScope`, `{ kind: 'generated' }` for a tree the CLI wrote into the project (a `.gen.ts`, or the `app` root derived from personas), and `{ kind: 'addon', package, displayName }` for one an installed addon declared. An addon's build stamps its own package and display name on its trees, and the host keeps that name while recording the package it actually installed. `MetaService.getScopesMeta()` reads the result, and the console's all-meta payload carries it as `scopes`.
+
+  The console's Scopes page becomes **Permissions** and is grouped by that origin: the app's own permissions first, then what Pikku generated into the project, then one card per addon (Pikku's own before third-party, each alphabetical), each card folding to its header — the app's own starts open, every addon's starts folded, and any search or filter opens them all. Above the cards, two filters narrow the page to what one role is given (or to what no role is given yet) and to one source. A permission group no longer says "Not part of any role yet" above lines that are each given to a role.
+
+- Updated dependencies [0c865d9]
+- Updated dependencies [c36b066]
+- Updated dependencies [0963b73]
+  - @pikku/core@0.12.137
+
 ## 0.12.101
 
 ### Patch Changes

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

@@ -0,0 +1,8 @@
+import * as ts from 'typescript';
+import type { InspectorState, InspectorLogger } from '../types.js';
+/**
+ * Detect `defineScreens({ title, icon, screens })` and record the manifest.
+ * A screen with a field that is not a literal is reported and left out: a
+ * navigation entry the host cannot read would otherwise vanish with no sign.
+ */
+export declare function addDefineScreens(node: ts.Node, state: InspectorState, logger: InspectorLogger): void;

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

@@ -0,0 +1,140 @@
+import * as ts from 'typescript';
+import { ErrorCode } from '../error-codes.js';
+const propName = (prop) => {
+    if (!ts.isPropertyAssignment(prop))
+        return undefined;
+    return ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)
+        ? prop.name.text
+        : undefined;
+};
+const stringArray = (node) => {
+    if (!ts.isArrayLiteralExpression(node))
+        return undefined;
+    const values = [];
+    for (const element of node.elements) {
+        if (!ts.isStringLiteral(element))
+            return undefined;
+        values.push(element.text);
+    }
+    return values;
+};
+/**
+ * The module specifier of `() => import('./screens/x')`. Anything else cannot
+ * be handed to the host's bundler as a lazy import, so it is not read.
+ */
+const lazyImportSpecifier = (node) => {
+    if (!ts.isArrowFunction(node))
+        return undefined;
+    const body = node.body;
+    if (!ts.isCallExpression(body) ||
+        body.expression.kind !== ts.SyntaxKind.ImportKeyword)
+        return undefined;
+    const [specifier] = body.arguments;
+    return specifier && ts.isStringLiteral(specifier) ? specifier.text : undefined;
+};
+/**
+ * Detect `defineScreens({ title, icon, screens })` and record the manifest.
+ * A screen with a field that is not a literal is reported and left out: a
+ * navigation entry the host cannot read would otherwise vanish with no sign.
+ */
+export function addDefineScreens(node, state, logger) {
+    if (!ts.isCallExpression(node))
+        return;
+    const { expression, arguments: args } = node;
+    if (!ts.isIdentifier(expression) || expression.text !== 'defineScreens')
+        return;
+    const [firstArg] = args;
+    if (!firstArg || !ts.isObjectLiteralExpression(firstArg))
+        return;
+    const fail = (message) => logger.critical(ErrorCode.ADDON_SCREENS_NOT_STATIC, message);
+    let title;
+    let icon;
+    const screens = [];
+    for (const prop of firstArg.properties) {
+        const key = propName(prop);
+        if (!key || !ts.isPropertyAssignment(prop))
+            continue;
+        if (key === 'title' && ts.isStringLiteral(prop.initializer)) {
+            title = prop.initializer.text;
+        }
+        else if (key === 'icon' && ts.isStringLiteral(prop.initializer)) {
+            icon = prop.initializer.text;
+        }
+        else if (key === 'screens') {
+            if (!ts.isArrayLiteralExpression(prop.initializer)) {
+                fail(`defineScreens's screens must be an array literal, got: ${prop.initializer.getText()}`);
+                continue;
+            }
+            for (const element of prop.initializer.elements) {
+                if (!ts.isObjectLiteralExpression(element)) {
+                    fail(`A defineScreens screen must be an object literal, got: ${element.getText()}`);
+                    continue;
+                }
+                let path;
+                let screenTitle;
+                let nav;
+                let scopes;
+                let component;
+                let app;
+                for (const field of element.properties) {
+                    const fieldKey = propName(field);
+                    if (!fieldKey || !ts.isPropertyAssignment(field))
+                        continue;
+                    const value = field.initializer;
+                    if (fieldKey === 'path' && ts.isStringLiteral(value)) {
+                        path = value.text;
+                    }
+                    else if (fieldKey === 'title' && ts.isStringLiteral(value)) {
+                        screenTitle = value.text;
+                    }
+                    else if (fieldKey === 'nav' &&
+                        (value.kind === ts.SyntaxKind.TrueKeyword ||
+                            value.kind === ts.SyntaxKind.FalseKeyword)) {
+                        nav = value.kind === ts.SyntaxKind.TrueKeyword;
+                    }
+                    else if (fieldKey === 'scopes') {
+                        scopes = stringArray(value);
+                        if (!scopes) {
+                            fail(`A screen's scopes must be an array of string literals, got: ${value.getText()}`);
+                        }
+                    }
+                    else if (fieldKey === 'component') {
+                        component = lazyImportSpecifier(value);
+                        if (!component) {
+                            fail(`A screen's component must be () => import('<literal>'), got: ${value.getText()}`);
+                        }
+                    }
+                    else if (fieldKey === 'app' && ts.isStringLiteral(value)) {
+                        app = value.text;
+                    }
+                }
+                if (!path || !screenTitle || (!component && !app)) {
+                    fail(`A defineScreens screen needs a literal path and title, and either a lazy component or an app: ${element.getText()}`);
+                    continue;
+                }
+                if (component && app) {
+                    fail(`Screen '${path}' sets both component and app; a screen is one or the other`);
+                    continue;
+                }
+                screens.push({
+                    path,
+                    title: screenTitle,
+                    ...(nav !== undefined ? { nav } : {}),
+                    ...(scopes ? { scopes } : {}),
+                    ...(component ? { component } : { app: app }),
+                });
+            }
+        }
+    }
+    if (!title) {
+        fail(`defineScreens needs a literal title`);
+        return;
+    }
+    logger.debug(`• Found defineScreens: ${title} (${screens.length} screens)`);
+    state.screensManifest = {
+        title,
+        ...(icon ? { icon } : {}),
+        file: node.getSourceFile().fileName,
+        screens,
+    };
+}

package/dist/add/add-scope.d.ts

@@ -1,2 +1,9 @@
 import type { AddWiring } from '../types.js';
+/**
+ * Folds `declareScopes` ids into `state.scopes.definitions`. An id the
+ * definitions already hold (an addon's tree, a `defineScope`) is left alone;
+ * a missing one is added as a bare node under its root, creating the root when
+ * nothing declared it.
+ */
+export declare const applyDeclaredScopes: (state: Parameters<AddWiring>[3]) => void;
 export declare const addScope: AddWiring;

package/dist/add/add-scope.js

@@ -84,11 +84,63 @@ const extractScopeNodes = (obj, scopeName, logger) => {
 const unwrapAs = (node) => ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
     ? unwrapAs(node.expression)
     : node;
+/**
+ * Records the ids of a `declareScopes([...])` call. They are merged into the
+ * definitions later (`applyDeclaredScopes`), after addon scope trees have
+ * loaded, so an addon's richer declaration is never shadowed by a bare id.
+ */
+const addDeclareScopes = (logger, node, state) => {
+    const arg = node.arguments[0] && unwrapAs(node.arguments[0]);
+    if (!arg || !ts.isArrayLiteralExpression(arg)) {
+        return;
+    }
+    const sourceFile = node.getSourceFile().fileName;
+    for (const element of arg.elements) {
+        if (!ts.isStringLiteralLike(element)) {
+            logger.critical(ErrorCode.NON_LITERAL_WIRE_NAME, 'declareScopes takes string literal scope ids.');
+            continue;
+        }
+        const id = element.text;
+        if (!id.split(SEPARATOR).every((s) => isValidSegment(s, id, logger))) {
+            continue;
+        }
+        state.scopes.declared ??= new Map();
+        if (!state.scopes.declared.has(id)) {
+            state.scopes.declared.set(id, sourceFile);
+        }
+    }
+    state.scopes.files.add(sourceFile);
+};
+/**
+ * Folds `declareScopes` ids into `state.scopes.definitions`. An id the
+ * definitions already hold (an addon's tree, a `defineScope`) is left alone;
+ * a missing one is added as a bare node under its root, creating the root when
+ * nothing declared it.
+ */
+export const applyDeclaredScopes = (state) => {
+    for (const [id, sourceFile] of state.scopes.declared ?? []) {
+        const [rootName, ...rest] = id.split(SEPARATOR);
+        let root = state.scopes.definitions.find((d) => d.name === rootName);
+        if (!root) {
+            root = { name: rootName, sourceFile };
+            state.scopes.definitions.push(root);
+        }
+        let level = root;
+        for (const segment of rest) {
+            level.scopes ??= {};
+            level = level.scopes[segment] ??= {};
+        }
+    }
+};
 export const addScope = (logger, node, checker, state, _options) => {
     if (!ts.isCallExpression(node)) {
         return;
     }
     const expression = node.expression;
+    if (ts.isIdentifier(expression) && expression.text === 'declareScopes') {
+        addDeclareScopes(logger, node, state);
+        return;
+    }
     if (!ts.isIdentifier(expression) || expression.text !== 'defineScope') {
         return;
     }
@@ -101,6 +153,11 @@ export const addScope = (logger, node, checker, state, _options) => {
         return;
     }
     const sourceFile = node.getSourceFile().fileName;
+    // A `.gen.ts` is one the CLI wrote into the project, the same test
+    // `claimSingleDeclaration` exempts it by.
+    const origin = sourceFile.endsWith('.gen.ts')
+        ? { kind: 'generated' }
+        : { kind: 'app' };
     // Roots are keyed exactly like the nodes beneath them, so each property of
     // the call's single argument is one tree.
     for (const prop of unwrapped.properties) {
@@ -141,6 +198,7 @@ export const addScope = (logger, node, checker, state, _options) => {
             description: descriptionValue || undefined,
             scopes,
             sourceFile,
+            origin,
         });
     }
 };

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

@@ -87,7 +87,8 @@ 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))
@@ -99,8 +100,10 @@ export function addWireAddon(node, state, logger) {
     let expose;
     let mcpEndpoint;
     let auth;
+    let ui;
     let tags;
     let scopes;
+    let uses;
     let secretOverrides;
     let variableOverrides;
     let credentialOverrides;
@@ -108,6 +111,9 @@ export function addWireAddon(node, state, logger) {
     let credentialGrants;
     let globalSecrets;
     let globalCredentials;
+    let contentBucket;
+    let contentGrants;
+    let globalContent;
     for (const prop of firstArg.properties) {
         if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
             continue;
@@ -154,12 +160,25 @@ export function addWireAddon(node, state, logger) {
                 prop.initializer.kind === ts.SyntaxKind.FalseKeyword)) {
             auth = prop.initializer.kind === ts.SyntaxKind.TrueKeyword;
         }
+        else if (key === 'ui' &&
+            (prop.initializer.kind === ts.SyntaxKind.TrueKeyword ||
+                prop.initializer.kind === ts.SyntaxKind.FalseKeyword)) {
+            ui = prop.initializer.kind === ts.SyntaxKind.TrueKeyword;
+        }
         else if (key === 'tags') {
             tags = parseStringArray(prop.initializer);
         }
         else if (key === 'scopes') {
             scopes = parseStringArray(prop.initializer);
         }
+        else if (key === 'uses') {
+            if (ts.isObjectLiteralExpression(prop.initializer)) {
+                uses = parseStringRecord(prop.initializer);
+            }
+            else {
+                logger.critical(ErrorCode.ADDON_EXPOSE_NOT_STATIC, `wireAddon's uses must be an object literal, got: ${prop.initializer.getText()}`);
+            }
+        }
         else if (key === 'secretOverrides' &&
             ts.isObjectLiteralExpression(prop.initializer)) {
             secretOverrides = parseStringRecord(prop.initializer);
@@ -190,12 +209,26 @@ export function addWireAddon(node, state, logger) {
                 ? prop.initializer.text
                 : prop.initializer.getText();
         }
+        else if (key === 'contentBucket' &&
+            ts.isStringLiteral(prop.initializer)) {
+            contentBucket = prop.initializer.text;
+        }
+        else if (key === 'contentGrants' &&
+            ts.isObjectLiteralExpression(prop.initializer)) {
+            contentGrants = parseStringRecord(prop.initializer);
+        }
+        else if (key === 'globalContent') {
+            globalContent = ts.isStringLiteral(prop.initializer)
+                ? prop.initializer.text
+                : prop.initializer.getText();
+        }
     }
     if (!name || !pkg)
         return;
-    logger.debug(`• Found wireAddon: ${name} → ${pkg}`);
+    logger.debug(`• Found ${expression.text}: ${name} → ${pkg}`);
     state.rpc.wireAddonDeclarations.set(name, {
         package: pkg,
+        ...(ui ? { ui } : {}),
         file: node.getSourceFile().fileName,
         rpcEndpoint,
         mcp,
@@ -204,6 +237,7 @@ export function addWireAddon(node, state, logger) {
         auth,
         tags,
         scopes,
+        uses,
         secretOverrides,
         variableOverrides,
         credentialOverrides,
@@ -211,6 +245,9 @@ export function addWireAddon(node, state, logger) {
         credentialGrants,
         globalSecrets,
         globalCredentials,
+        contentBucket,
+        contentGrants,
+        globalContent,
     });
     state.rpc.usedAddons.add(name);
     state.rpc.wireAddonFiles.add(node.getSourceFile().fileName);

package/dist/error-codes.d.ts

@@ -36,6 +36,11 @@ export declare enum ErrorCode {
     ADDON_MCP_FUNCTION_NOT_FOUND = "PKU341",
     ADDON_EXPOSE_FUNCTION_NOT_FOUND = "PKU343",
     ADDON_EXPOSE_NOT_STATIC = "PKU344",
+    ADDON_SCREENS_NOT_STATIC = "PKU345",
+    ADDON_UI_HAS_NO_SCREENS = "PKU346",
+    ADDON_USES_NOT_WIRED = "PKU347",
+    ADDON_NEEDS_NOT_MAPPED = "PKU348",
+    ADDON_CONTENT_GRANT_INVALID = "PKU349",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",

package/dist/error-codes.js

@@ -39,6 +39,11 @@ export var ErrorCode;
     ErrorCode["ADDON_MCP_FUNCTION_NOT_FOUND"] = "PKU341";
     ErrorCode["ADDON_EXPOSE_FUNCTION_NOT_FOUND"] = "PKU343";
     ErrorCode["ADDON_EXPOSE_NOT_STATIC"] = "PKU344";
+    ErrorCode["ADDON_SCREENS_NOT_STATIC"] = "PKU345";
+    ErrorCode["ADDON_UI_HAS_NO_SCREENS"] = "PKU346";
+    ErrorCode["ADDON_USES_NOT_WIRED"] = "PKU347";
+    ErrorCode["ADDON_NEEDS_NOT_MAPPED"] = "PKU348";
+    ErrorCode["ADDON_CONTENT_GRANT_INVALID"] = "PKU349";
     // Database schema codegen warnings
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { inspect, getInitialInspectorState } from './inspector.js';
 export type { TypesMap } from './types-map.js';
-export type { AddonConfig, AuthDefinition, CredentialOverrideMeta, InspectorDiagnostic, InspectorFilters, InspectorHTTPState, InspectorLogger, InspectorMiddlewareState, InspectorOptions, InspectorPermissionState, InspectorState, MetaInputTypes, MiddlewareGroupMeta, MiddlewareRegistration, SchemaRef, } from './types.js';
+export type { AddonConfig, AuthDefinition, CredentialOverrideMeta, ScreensManifestMeta, AddonScreenMeta, InspectorDiagnostic, InspectorFilters, InspectorHTTPState, InspectorLogger, InspectorMiddlewareState, InspectorOptions, InspectorPermissionState, 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';
@@ -25,5 +25,6 @@ export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
 export type { SerializedWorkflowGraph, SerializedWorkflowGraphs, } from './utils/workflow/graph/index.js';
 export { resolveCoreType } from './utils/resolve-core-type.js';
 export { readModuleSpecifiers } from './utils/read-module-specifiers.js';
+export { readJsxLiteralText } from './utils/read-jsx-literal-text.js';
 export { readTsconfigOutDir } from './utils/read-tsconfig-out-dir.js';
 export { addonResolutionDirs, createAddonResolver, } from './utils/addon-resolution.js';

package/dist/index.js

@@ -14,5 +14,6 @@ export { getFilesAndMethods } from './utils/get-files-and-methods.js';
 export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
 export { resolveCoreType } from './utils/resolve-core-type.js';
 export { readModuleSpecifiers } from './utils/read-module-specifiers.js';
+export { readJsxLiteralText } from './utils/read-jsx-literal-text.js';
 export { readTsconfigOutDir } from './utils/read-tsconfig-out-dir.js';
 export { addonResolutionDirs, createAddonResolver, } from './utils/addon-resolution.js';

package/dist/inspector.js

@@ -1,4 +1,5 @@
 import * as ts from 'typescript';
+import { applyDeclaredScopes } from './add/add-scope.js';
 import { performance } from 'perf_hooks';
 import { dirname, relative, resolve } from 'path';
 import { visitSetup, visitFunctions, visitRoutes } from './visit.js';
@@ -8,7 +9,7 @@ import { findCommonAncestor } from './utils/find-root-dir.js';
 import { createSourceFileCacheHost } from './source-file-cache.js';
 import { createNestedProjectFilter } from './utils/nested-project-filter.js';
 import { toProgramPath } from './utils/program-path.js';
-import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, registerDerivedOAuth2AppSecrets, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateScenarioFeatures, validateWorkflowGraphAddons, } from './utils/post-process.js';
+import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateAddonUses, validateAddonContentGrants, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, registerDerivedOAuth2AppSecrets, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateScenarioFeatures, validateWorkflowGraphAddons, } from './utils/post-process.js';
 import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js';
 import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js';
 import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js';
@@ -426,8 +427,11 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         validateSecretOverrides(logger, state);
         validateVariableOverrides(logger, state);
         validateCredentialOverrides(logger, state);
+        validateAddonUses(logger, state);
+        validateAddonContentGrants(logger, state);
         validateRemoteAddonDependencies(logger, state);
         validateRemoteAddonAuth(logger, state);
+        applyDeclaredScopes(state);
         validateScopeReferences(logger, state);
         validateSystemRoleScopes(logger, state);
         validatePersonaRoles(logger, state);

package/dist/types.d.ts

@@ -491,7 +491,38 @@ export type CredentialOverrideMeta = string | {
     name?: string;
     mode?: 'singleton' | 'wire';
 };
+/** A screen of an addon as `defineScreens` declares it, read statically. */
+export type AddonScreenMeta = {
+    path: string;
+    title: string;
+    nav?: boolean;
+    scopes?: string[];
+} & ({
+    component: string;
+    app?: undefined;
+} | {
+    app: string;
+    component?: undefined;
+});
+export type ScreensManifestMeta = {
+    title: string;
+    icon?: string;
+    /** The source file whose `defineScreens` call declared this manifest. */
+    file: string;
+    screens: AddonScreenMeta[];
+    /**
+     * The addon's role: every scope its own functions require, derived by
+     * `pikku all` and never declared. Absent from the raw `defineScreens` 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[];
+};
 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>;
     rootDir: string;
     singletonServicesTypeImportMap: PathToNameAndType;
     wireServicesTypeImportMap: PathToNameAndType;
@@ -605,7 +636,11 @@ export interface InspectorState {
             package: string;
             /** The app source file whose `wireAddon` call declared this instance. */
             file?: string;
+            /** 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. */
+            uses?: Record<string, string>;
             /**
              * `true` offers every function the addon declared `mcp: true`; a list
              * names the functions to offer, whatever the addon declared. Absent
@@ -660,6 +695,13 @@ export interface InspectorState {
              * `CredentialService` instead of one scoped to its declared credentials.
              */
             globalCredentials?: string;
+            contentBucket?: string;
+            contentGrants?: Record<string, string>;
+            /**
+             * The app's stated reason for handing this instance the whole
+             * `ContentService` instead of one scoped to its own folder.
+             */
+            globalContent?: string;
         }>;
         wireAddonFiles: Set<string>;
     };
@@ -731,6 +773,8 @@ export interface InspectorState {
     scopes: {
         definitions: ScopeDefinitions;
         files: Set<string>;
+        /** Ids from `declareScopes([...])`, merged into `definitions` once addon scopes are loaded. */
+        declared?: Map<string, string>;
     };
     systemRoles: {
         definitions: SystemRoleDefinitions;

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

@@ -8,11 +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;
-/**
- * After the setup sweep discovers wireAddon() declarations, load each addon
- * package's function metadata so that wiring handlers (channels, HTTP routes,
- * schedules, etc.) can look up addon function types during the routes sweep.
- */
 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

@@ -181,6 +181,27 @@ export const namespaceAddonWebhookSources = (sources, namespace) => {
  * package's function metadata so that wiring handlers (channels, HTTP routes,
  * schedules, etc.) can look up addon function types during the routes sweep.
  */
+const loadScreensManifest = async (require, packageName) => {
+    const path = resolveAddonMeta(require, packageName, 'screens/pikku-screens-meta');
+    if (!path)
+        return null;
+    return JSON.parse(await readFile(path, 'utf-8'));
+};
+const readAddonNeeds = async (dirs, packageName) => {
+    const dir = findInstalledPackageDir(dirs, packageName);
+    if (!dir)
+        return [];
+    try {
+        const pkg = JSON.parse(await readFile(join(dir, 'package.json'), 'utf-8'));
+        const uses = pkg?.pikku?.uses;
+        return Array.isArray(uses)
+            ? uses.filter((u) => typeof u === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+};
 export async function loadAddonFunctionsMeta(logger, state) {
     const { wireAddonDeclarations } = state.rpc;
     if (wireAddonDeclarations.size === 0)
@@ -194,6 +215,37 @@ export async function loadAddonFunctionsMeta(logger, state) {
         const dirs = addonResolutionDirs(state.rootDir, decl.file);
         const require = createAddonResolver(dirs);
         try {
+            for (const needed of await readAddonNeeds(dirs, decl.package)) {
+                if (!decl.uses?.[needed]) {
+                    logger.critical(ErrorCode.ADDON_NEEDS_NOT_MAPPED, `${decl.package} needs ${needed}, but wireAddon('${namespace}') does not map it. Wire ${needed} and add uses: { '${needed}': '<name>' } to this wireAddon.`);
+                }
+            }
+            if (decl.ui) {
+                let manifest;
+                let unreadable = false;
+                try {
+                    manifest = await loadScreensManifest(require, decl.package);
+                }
+                catch (e) {
+                    logger.critical(ErrorCode.ADDON_UI_HAS_NO_SCREENS, `wireAddon('${namespace}') sets ui: true, but the screens manifest of ${decl.package} could not be read: ${e instanceof Error ? e.message : e}`);
+                    unreadable = true;
+                }
+                if (unreadable) {
+                    // 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 defineScreens call to the package, or drop ui.`);
+                }
+                else {
+                    ;
+                    (state.addonScreens ??= {})[namespace] = {
+                        ...manifest,
+                        scopes: [
+                            ...new Set([...(manifest.scopes ?? []), ...(decl.scopes ?? [])]),
+                        ].sort(),
+                    };
+                }
+            }
             // Verbose first. `description` is one of the fields stripped from the
             // minimal copy, and it is what an addon's function is offered to a model
             // under — both as an MCP tool below and as an agent tool. Read the minimal
@@ -296,7 +348,16 @@ export async function loadAddonFunctionsMeta(logger, state) {
                 for (const [key, def] of Object.entries(scopesMeta)) {
                     const existing = state.scopes.definitions.find((d) => d.name === key);
                     if (!existing) {
-                        state.scopes.definitions.push(def);
+                        // The addon's build stamped its own name on the trees it declared;
+                        // the package it was installed as is the one this host knows.
+                        const origin = {
+                            kind: 'addon',
+                            package: decl.package,
+                            displayName: def.origin?.kind === 'addon'
+                                ? def.origin.displayName
+                                : undefined,
+                        };
+                        state.scopes.definitions.push({ ...def, origin });
                         logger.debug(`Loaded addon scope '${key}' from ${decl.package}`);
                     }
                 }

package/dist/utils/post-process.d.ts

@@ -31,6 +31,8 @@ export declare function extractWireNames(list?: Array<MiddlewareMetadata | Permi
  */
 export declare function aggregateRequiredServices(state: InspectorState | Omit<InspectorState, "typesLookup">): void;
 export declare function validateSecretOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function validateAddonUses(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function validateAddonContentGrants(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
 export declare function validateCredentialOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
 export declare function validateVariableOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
 /**

package/dist/utils/post-process.js

@@ -393,6 +393,39 @@ export function validateSecretOverrides(logger, state) {
         }
     }
 }
+export function validateAddonUses(logger, state) {
+    const { wireAddonDeclarations } = state.rpc;
+    if (!wireAddonDeclarations || wireAddonDeclarations.size === 0)
+        return;
+    for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
+        for (const [pkg, target] of Object.entries(addonDecl.uses ?? {})) {
+            const wired = wireAddonDeclarations.get(target);
+            if (!wired) {
+                logger.critical(ErrorCode.ADDON_USES_NOT_WIRED, `Addon '${namespace}' uses '${pkg}' as '${target}', but no addon is wired under the name '${target}'. Wired: ${Array.from(wireAddonDeclarations.keys()).join(", ")}`);
+            }
+            else if (wired.package !== pkg) {
+                logger.critical(ErrorCode.ADDON_USES_NOT_WIRED, `Addon '${namespace}' uses '${pkg}' as '${target}', but '${target}' is wired from '${wired.package}'.`);
+            }
+        }
+    }
+}
+export function validateAddonContentGrants(logger, state) {
+    const { wireAddonDeclarations } = state.rpc;
+    if (!wireAddonDeclarations || wireAddonDeclarations.size === 0)
+        return;
+    const buckets = new Set(Array.from(wireAddonDeclarations.entries()).map(([namespace, decl]) => decl.contentBucket ?? namespace));
+    for (const [namespace, decl] of wireAddonDeclarations.entries()) {
+        for (const [prefix, mode] of Object.entries(decl.contentGrants ?? {})) {
+            if (mode !== "read" && mode !== "write") {
+                logger.critical(ErrorCode.ADDON_CONTENT_GRANT_INVALID, `Addon '${namespace}' grants '${prefix}' as '${mode}', but a content grant must be 'read' or 'write'.`);
+            }
+            const first = prefix.split("/").find((segment) => segment !== "");
+            if (!first || !buckets.has(first)) {
+                logger.critical(ErrorCode.ADDON_CONTENT_GRANT_INVALID, `Addon '${namespace}' grants content under '${prefix}', but '${first ?? ""}' is not the content bucket of any wired addon. Buckets: ${Array.from(buckets).join(", ")}`);
+            }
+        }
+    }
+}
 export function validateCredentialOverrides(logger, state) {
     const { wireAddonDeclarations } = state.rpc;
     if (!wireAddonDeclarations || wireAddonDeclarations.size === 0)

package/dist/utils/read-jsx-literal-text.d.ts

@@ -0,0 +1,5 @@
+export type JsxLiteralText = {
+    text: string;
+    line: number;
+};
+export declare const readJsxLiteralText: (fileName: string, content: string) => JsxLiteralText[];

package/dist/utils/read-jsx-literal-text.js

@@ -0,0 +1,126 @@
+import ts from 'typescript';
+const TEXT_ATTRIBUTES = new Set([
+    'placeholder',
+    'title',
+    'alt',
+    'aria-label',
+    'label',
+    'description',
+]);
+const TEXT_PROPERTIES = new Set([
+    ...TEXT_ATTRIBUTES,
+    'text',
+    'body',
+    'why',
+    'hint',
+    'caption',
+    'heading',
+    'subtitle',
+    'message',
+    'tooltip',
+]);
+const NON_TEXT_ATTRIBUTES = new Set([
+    'className',
+    'class',
+    'style',
+    'd',
+    'viewBox',
+    'preserveAspectRatio',
+    'points',
+    'transform',
+    'fill',
+    'stroke',
+    'href',
+    'src',
+    'rel',
+    'target',
+    'role',
+    'to',
+    'id',
+    'name',
+    'type',
+    'value',
+    'key',
+]);
+const isProse = (text) => /^\p{Lu}[^\s]*(\s+[^\s]+)+/u.test(text.trim()) &&
+    !/[:/[\]=_#]/.test(text.split(/\s+/)[0] ?? '');
+const isSentence = (text) => /\p{L}+\s+\p{L}+/u.test(text);
+const hasLetter = (text) => /\p{L}/u.test(text);
+const isLiteral = (node) => ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node);
+const rendered = (node) => {
+    if (isLiteral(node))
+        return [node];
+    if (ts.isParenthesizedExpression(node))
+        return rendered(node.expression);
+    if (ts.isConditionalExpression(node)) {
+        return [...rendered(node.whenTrue), ...rendered(node.whenFalse)];
+    }
+    if (ts.isBinaryExpression(node)) {
+        const operator = node.operatorToken.kind;
+        if (operator === ts.SyntaxKind.AmpersandAmpersandToken) {
+            return rendered(node.right);
+        }
+        if (operator === ts.SyntaxKind.BarBarToken ||
+            operator === ts.SyntaxKind.QuestionQuestionToken) {
+            return [...rendered(node.left), ...rendered(node.right)];
+        }
+    }
+    return [];
+};
+export const readJsxLiteralText = (fileName, content) => {
+    const source = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const found = [];
+    const seen = new Set();
+    const add = (node, text) => {
+        if (!hasLetter(text) || seen.has(node.getStart(source)))
+            return;
+        seen.add(node.getStart(source));
+        const { line } = source.getLineAndCharacterOfPosition(node.getStart(source));
+        found.push({ text: text.trim(), line: line + 1 });
+    };
+    const visit = (node) => {
+        if (ts.isJsxText(node)) {
+            add(node, node.text);
+        }
+        else if (ts.isJsxExpression(node) &&
+            node.expression &&
+            (ts.isJsxElement(node.parent) || ts.isJsxFragment(node.parent))) {
+            for (const literal of rendered(node.expression))
+                add(literal, literal.text);
+        }
+        else if (ts.isJsxAttribute(node) && node.initializer) {
+            const name = node.name.getText(source);
+            const value = ts.isJsxExpression(node.initializer)
+                ? node.initializer.expression
+                : node.initializer;
+            if (value &&
+                (ts.isStringLiteral(value) ||
+                    ts.isNoSubstitutionTemplateLiteral(value)) &&
+                (TEXT_ATTRIBUTES.has(name) ||
+                    (!NON_TEXT_ATTRIBUTES.has(name) &&
+                        !name.startsWith('data-') &&
+                        isSentence(value.text)))) {
+                add(value, value.text);
+            }
+        }
+        else if (ts.isPropertyAssignment(node) &&
+            TEXT_PROPERTIES.has(node.name.getText(source)) &&
+            (ts.isStringLiteral(node.initializer) ||
+                ts.isNoSubstitutionTemplateLiteral(node.initializer))) {
+            add(node.initializer, node.initializer.text);
+        }
+        if (isLiteral(node) &&
+            isProse(node.text) &&
+            !ts.isImportDeclaration(node.parent) &&
+            !ts.isExportDeclaration(node.parent) &&
+            !ts.isLiteralTypeNode(node.parent) &&
+            !(ts.isPropertyAssignment(node.parent) && node.parent.name === node) &&
+            !(ts.isJsxAttribute(node.parent) &&
+                NON_TEXT_ATTRIBUTES.has(node.parent.name.getText(source)))) {
+            add(node, node.text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return found;
+};

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

@@ -204,6 +204,9 @@ export interface SerializableInspectorState {
                 credentialGrants?: string[];
                 globalSecrets?: string;
                 globalCredentials?: string;
+                contentBucket?: string;
+                contentGrants?: Record<string, string>;
+                globalContent?: string;
             }
         ]>;
         wireAddonFiles: string[];
@@ -317,6 +320,8 @@ export interface SerializableInspectorState {
     openAPISpec: Record<string, any> | null;
     diagnostics: InspectorDiagnostic[];
     addonFunctions: InspectorState['addonFunctions'];
+    screensManifest?: InspectorState['screensManifest'];
+    addonScreens?: InspectorState['addonScreens'];
     exportedContracts: InspectorState['exportedContracts'];
 }
 /**

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

@@ -182,6 +182,8 @@ export function serializeInspectorState(state) {
         openAPISpec: state.openAPISpec,
         diagnostics: state.diagnostics,
         addonFunctions: state.addonFunctions,
+        screensManifest: state.screensManifest,
+        addonScreens: state.addonScreens,
         exportedContracts: state.exportedContracts,
     };
 }
@@ -378,6 +380,8 @@ export function deserializeInspectorState(data) {
         openAPISpec: data.openAPISpec || null,
         diagnostics: data.diagnostics || [],
         addonFunctions: data.addonFunctions || {},
+        screensManifest: data.screensManifest,
+        addonScreens: data.addonScreens,
         exportedContracts: data.exportedContracts || {
             http: {},
             cli: {},

package/dist/visit.js

@@ -15,6 +15,7 @@ import { addChannel } from './add/add-channel.js';
 import { addGateway } from './add/add-gateway.js';
 import { addRPCInvocations } from './add/add-rpc-invocations.js';
 import { addWireAddon } from './add/add-wire-addon.js';
+import { addDefineScreens } from './add/add-define-screens.js';
 import { addWireRemoteAddon } from './add/add-wire-remote-addon.js';
 import { addMiddleware } from './add/add-middleware.js';
 import { addPermission } from './add/add-permission.js';
@@ -47,6 +48,7 @@ export const visitSetup = (logger, checker, node, state, options) => {
     addOutgoingWebhook(logger, node, checker, state);
     addRPCInvocations(node, state, logger);
     addWireAddon(node, state, logger);
+    addDefineScreens(node, state, logger);
     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.101",
+  "version": "0.12.103",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -54,10 +54,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.136"
+    "@pikku/core": "^0.12.139"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.136",
+    "@pikku/core": "^0.12.139",
     "@types/node": "^24.13.3"
   },
   "engines": {