@pikku/inspector 0.12.112 → 0.12.113

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

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import { existsSync, readFileSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { dirname, join } from 'path';
 import { ErrorCode } from '../error-codes.js';
 const SCOPES = ['studio', 'team', 'project'];
@@ -110,6 +110,7 @@ const readScreen = (element, fail) => {
     let scopes;
     let component;
     let app;
+    let agent;
     let ok = true;
     for (const field of element.properties) {
         const key = propName(field);
@@ -136,6 +137,8 @@ const readScreen = (element, fail) => {
             read = replaces = booleanLiteral(value);
         else if (key === 'needsApp')
             read = needsApp = booleanLiteral(value);
+        else if (key === 'agent')
+            read = agent = ts.isStringLiteral(value) ? value.text : undefined;
         else if (key === 'layout')
             read = layout = oneOf(value, ['bare']);
         else if (key === 'scopes') {
@@ -182,6 +185,7 @@ const readScreen = (element, fail) => {
         ...(needsApp !== undefined ? { needsApp } : {}),
         ...(layout ? { layout } : {}),
         ...(scopes ? { scopes } : {}),
+        ...(agent !== undefined ? { agent } : {}),
         ...(component ? { component } : { app: app }),
     };
 };
@@ -195,7 +199,8 @@ export function addPikkuStudio(node, state, logger) {
     if (!ts.isCallExpression(node))
         return;
     const { expression, arguments: args } = node;
-    if (!ts.isIdentifier(expression) || expression.text !== 'definePlugin' && expression.text !== 'pikkuStudio')
+    if (!ts.isIdentifier(expression) ||
+        (expression.text !== 'definePlugin' && expression.text !== 'pikkuStudio'))
         return;
     const [firstArg] = args;
     if (!firstArg || !ts.isObjectLiteralExpression(firstArg))
@@ -259,6 +264,34 @@ const packageRoot = (file) => {
         dir = parent;
     }
 };
+const AGENT_NAME = /^[a-z][a-z0-9-]*$/;
+const STUDIO_AGENT = /^studio:[a-z][a-z0-9-]*$/;
+/** The text of a file that exists and is not blank, else undefined. */
+const readNonEmpty = (file) => {
+    try {
+        if (!statSync(file).isFile())
+            return undefined;
+        const text = readFileSync(file, 'utf-8');
+        return text.trim() === '' ? undefined : text;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The `key: value` lines of a leading `---` block; undefined when there is none. */
+const readFrontmatter = (text) => {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+    if (!match)
+        return undefined;
+    const fields = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const pair = /^([A-Za-z][\w-]*):\s*(.*?)\s*$/.exec(line);
+        if (!pair)
+            continue;
+        fields[pair[1]] = pair[2].replace(/^(['"])(.*)\1$/, '$2');
+    }
+    return fields;
+};
 const readCatalog = (file) => {
     try {
         return JSON.parse(readFileSync(file, 'utf-8'));
@@ -299,6 +332,46 @@ export function validatePikkuStudio(logger, state) {
         }
     }
     for (const screen of studio.screens) {
+        const agent = screen.agent;
+        if (agent !== undefined) {
+            const invalid = (reason) => logger.critical(ErrorCode.STUDIO_SCREEN_AGENT_INVALID, `Screen '${screen.path}' has the agent '${agent}', ${reason}`);
+            if (agent.startsWith('studio:')) {
+                // An agent Studio ships: pikku cannot see it, so only the format is checked.
+                if (!STUDIO_AGENT.test(agent)) {
+                    invalid("which is not a valid agent: use a name for an agent the addon ships (lowercase letters, digits and hyphens, starting with a letter) or 'studio:<name>' for one Studio ships");
+                }
+            }
+            else if (!AGENT_NAME.test(agent)) {
+                invalid("which is not a valid agent: use a name for an agent the addon ships (lowercase letters, digits and hyphens, starting with a letter) or 'studio:<name>' for one Studio ships");
+            }
+            else {
+                const text = root
+                    ? readNonEmpty(join(root, 'agents', `${agent}.md`))
+                    : undefined;
+                const fields = text === undefined ? undefined : readFrontmatter(text);
+                if (text === undefined) {
+                    invalid(`but the addon has no non-empty agents/${agent}.md`);
+                }
+                else if (!fields) {
+                    invalid(`whose agents/${agent}.md has no frontmatter; it needs a title and a description`);
+                }
+                else {
+                    for (const field of ['title', 'description']) {
+                        const key = fields[field];
+                        if (!key) {
+                            invalid(`whose agents/${agent}.md frontmatter has no ${field}; it must be a message key`);
+                        }
+                        else if (!en || !Object.hasOwn(en, key)) {
+                            logger.critical(ErrorCode.STUDIO_MESSAGE_KEY_MISSING, `definePlugin uses the message key '${key}', which is missing from the addon's messages/en.json`);
+                        }
+                        else if (field === 'title')
+                            screen.agentTitle = key;
+                        else
+                            screen.agentDescription = key;
+                    }
+                }
+            }
+        }
         const badge = screen.nav?.badge;
         if (badge !== undefined && !state.functions.meta[badge]) {
             logger.critical(ErrorCode.STUDIO_BADGE_FUNCTION_NOT_FOUND, `Screen '${screen.path}' has the nav badge '${badge}', which names no function in this addon`);

package/dist/error-codes.d.ts

@@ -57,6 +57,7 @@ export declare enum ErrorCode {
     ADDON_CONTRIBUTORS_NOT_STATIC = "PKU362",
     ADDON_CONTRIBUTOR_UNKNOWN = "PKU363",
     ADDON_LEGACY_CONTRIBUTORS = "PKU364",
+    STUDIO_SCREEN_AGENT_INVALID = "PKU365",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",

package/dist/error-codes.js

@@ -60,6 +60,7 @@ export var ErrorCode;
     ErrorCode["ADDON_CONTRIBUTORS_NOT_STATIC"] = "PKU362";
     ErrorCode["ADDON_CONTRIBUTOR_UNKNOWN"] = "PKU363";
     ErrorCode["ADDON_LEGACY_CONTRIBUTORS"] = "PKU364";
+    ErrorCode["STUDIO_SCREEN_AGENT_INVALID"] = "PKU365";
     // Database schema codegen warnings
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";

package/dist/types.d.ts

@@ -548,6 +548,11 @@ export type StudioScreenMeta = {
     needsApp?: boolean;
     layout?: 'bare';
     scopes?: string[];
+    agent?: string;
+    /** Message key from the agent file's frontmatter, filled by validation. */
+    agentTitle?: string;
+    /** Message key from the agent file's frontmatter, filled by validation. */
+    agentDescription?: string;
 } & ({
     component: string;
     app?: undefined;

package/package.json

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