@pikku/inspector 0.12.99 → 0.12.102

package/CHANGELOG.md

@@ -1,3 +1,34 @@
+## 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
+
+- 9112494: `pikku knowledge validate` reports code that no note describes as a warning rather than info, and raises one `PKU960` diagnostic for it, so `--fail-on-warn` can gate on it and the "consistent" line no longer prints while notes are missing. A plain run still exits 0: only errors fail it.
+
+## 0.12.100
+
+### Patch Changes
+
+- 149faae: Webhook `receive` steps lose their boilerplate. `pikkuWebhookReceive` (from `#pikku/trigger` or `#pikku/addon/trigger`) declares one: it is public, typed to the raw request with a required `http`, and never registered as an RPC, and the inspector rejects a `receive` declared with any other wrapper. `parseJson` (in `@pikku/core/utils`, generated as `#pikku/utils` and `#pikku/addon/utils`) parses text or bytes and answers a body that is not JSON with a 400. A webhook source whose `method` includes `'head'` answers HEAD probes itself with a 200.
+
+  `receive` no longer returns `{ respond }`: a handshake returns nothing and writes its answer to `http.response`, like any other HTTP function. The webhook route no longer returns a fetch `Response` either. An HTTP function that returns nothing is now answered with whatever status its response has (200 unless it set another), no longer a forced 204. A webhook receive is also left out of contract versioning, since nothing but its own route calls it.
+
+- Updated dependencies [149faae]
+  - @pikku/core@0.12.136
+
 ## 0.12.99
 
 ### Patch Changes

package/dist/add/add-functions.js

@@ -361,6 +361,7 @@ export const addFunctions = (logger, node, checker, state, options) => {
     const pikkuFuncPattern = /pikku.*func/i;
     if (!pikkuFuncPattern.test(expression.text) &&
         expression.text !== 'pikkuScenario' &&
+        expression.text !== 'pikkuWebhookReceive' &&
         !SCENARIO_STEP_KINDS.has(expression.text)) {
         return;
     }
@@ -373,6 +374,10 @@ export const addFunctions = (logger, node, checker, state, options) => {
     // analyzer can tell it apart from an application workflow without having to
     // reach into the workflow graph.
     const isScenario = expression.text === 'pikkuScenario';
+    // A webhook source's `receive`. Only its source's route runs it, with the
+    // raw request, so like a scenario step it is bundled but never RPC-registered.
+    const isWebhookReceive = expression.text === 'pikkuWebhookReceive';
+    const notRpc = isScenarioStep || isWebhookReceive;
     // only handle calls like pikkuFunc(...)
     if (!ts.isIdentifier(expression) || !expression.text.startsWith('pikku')) {
         return;
@@ -817,6 +822,9 @@ export const addFunctions = (logger, node, checker, state, options) => {
             inputTypes = result.types;
         }
     }
+    // A receive's input is always the raw request, which no schema describes.
+    if (isWebhookReceive)
+        inputNames = [];
     // --- Output Extraction ---
     let outputNames = [];
     if (outputSchemaRef) {
@@ -1054,11 +1062,16 @@ export const addFunctions = (logger, node, checker, state, options) => {
         inputs: inputNames.filter((n) => n !== 'void') ?? null,
         outputs: outputNames.filter((n) => n !== 'void') ?? null,
         expose: expose || undefined,
-        auth: typeof auth === 'boolean' ? auth : undefined,
+        auth: isWebhookReceive
+            ? false
+            : typeof auth === 'boolean'
+                ? auth
+                : undefined,
         permissionsInBody: permissionsInBody || undefined,
         audit,
         remote: remote || undefined,
         scenarioStep: isScenarioStep || undefined,
+        webhookReceive: isWebhookReceive || undefined,
         scenario: isScenario || undefined,
         mcp: mcpEnabled || undefined,
         readonly: readonly_ || undefined,
@@ -1173,7 +1186,7 @@ export const addFunctions = (logger, node, checker, state, options) => {
             logger.error(`• Function with explicit name '${name}' is not exported, this is not allowed.`);
             return;
         }
-        if (remote && !isScenarioStep) {
+        if (remote && !notRpc) {
             state.rpc.invokedFunctions.add(pikkuFuncId);
             // The consumer-facing surface a wireRemoteAddon imports (mirrors exposedMeta)
             state.rpc.remoteMeta[name] = pikkuFuncId;
@@ -1182,7 +1195,7 @@ export const addFunctions = (logger, node, checker, state, options) => {
                 exportedName,
             });
         }
-        if (expose && !isScenarioStep) {
+        if (expose && !notRpc) {
             state.rpc.exposedMeta[name] = pikkuFuncId;
             state.rpc.exposedFiles.set(name, {
                 path: node.getSourceFile().fileName,
@@ -1191,7 +1204,7 @@ export const addFunctions = (logger, node, checker, state, options) => {
             // Track exposed RPC function for service aggregation
             state.serviceAggregation.usedFunctions.add(pikkuFuncId);
         }
-        if (!isScenarioStep) {
+        if (!notRpc) {
             // We add it to internal meta to allow autocomplete for everything
             state.rpc.internalMeta[name] = pikkuFuncId;
             if (version !== undefined) {

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-trigger.js

@@ -184,6 +184,12 @@ const addWireTriggerWebhookSource = (logger, node, checker, state, firstArg) =>
  */
 export const validateWebhookSourceTriggers = (logger, state) => {
     const sources = state.triggers.webhookSourceMeta;
+    for (const source of Object.values(sources)) {
+        const meta = source.receive && state.functions.meta[source.receive];
+        if (meta && meta.funcWrapper && !meta.webhookReceive) {
+            logger.error(`Webhook source '${source.name}' receives with '${source.receive}', a ${meta.funcWrapper}. Declare it with pikkuWebhookReceive so it is never callable as an RPC.`);
+        }
+    }
     for (const trigger of Object.keys(state.triggers.meta)) {
         const colon = trigger.indexOf(':');
         if (colon === -1)

package/dist/error-codes.d.ts

@@ -83,6 +83,7 @@ export declare enum ErrorCode {
     ADDON_WIRING_NOT_ALLOWED = "PKU920",
     ADDON_CONTRACT_HANDLERS_NOT_ALLOWED = "PKU921",
     RPC_INVOCATION_TYPE_CAST = "PKU940",
+    KNOWLEDGE_NOTE_MISSING = "PKU960",
     SECRET_SERVICE_ALIASED = "PKU950",
     SECRET_NOT_DECLARED = "PKU951",
     SECRET_KEY_NOT_STATIC = "PKU952",

package/dist/error-codes.js

@@ -108,6 +108,8 @@ export var ErrorCode;
     ErrorCode["ADDON_WIRING_NOT_ALLOWED"] = "PKU920";
     ErrorCode["ADDON_CONTRACT_HANDLERS_NOT_ALLOWED"] = "PKU921";
     ErrorCode["RPC_INVOCATION_TYPE_CAST"] = "PKU940";
+    // Knowledge base errors
+    ErrorCode["KNOWLEDGE_NOTE_MISSING"] = "PKU960";
     // Secret boundary errors
     ErrorCode["SECRET_SERVICE_ALIASED"] = "PKU950";
     ErrorCode["SECRET_NOT_DECLARED"] = "PKU951";

package/dist/index.d.ts

@@ -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';
@@ -428,6 +429,7 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         validateCredentialOverrides(logger, state);
         validateRemoteAddonDependencies(logger, state);
         validateRemoteAddonAuth(logger, state);
+        applyDeclaredScopes(state);
         validateScopeReferences(logger, state);
         validateSystemRoleScopes(logger, state);
         validatePersonaRoles(logger, state);

package/dist/types.d.ts

@@ -731,6 +731,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/contract-hashes.js

@@ -71,7 +71,9 @@ function resolveSchema(typeNames, allSchemas, typesMap) {
 export function buildCurrentContracts(functionsMeta, allSchemas, typesMap) {
     const result = new Map();
     for (const [funcId, meta] of Object.entries(functionsMeta)) {
-        if (meta.remote === true) {
+        // A webhook receive has no callers but its own route, so there is no
+        // contract for a version to protect.
+        if (meta.remote === true || meta.webhookReceive) {
             continue;
         }
         const parsed = parseVersionedId(funcId);
@@ -251,7 +253,7 @@ export function updateManifest(existing, currentContracts) {
 export function extractContractsFromMeta(functionsMeta) {
     const result = new Map();
     for (const [funcId, meta] of Object.entries(functionsMeta)) {
-        if (meta.remote === true || !meta.contractHash) {
+        if (meta.remote === true || meta.webhookReceive || !meta.contractHash) {
             continue;
         }
         const parsed = parseVersionedId(funcId);

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

@@ -296,7 +296,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.99",
+  "version": "0.12.102",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -54,10 +54,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.135"
+    "@pikku/core": "^0.12.137"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.135",
+    "@pikku/core": "^0.12.137",
     "@types/node": "^24.13.3"
   },
   "engines": {