@piewf/cli 5.17.1 → 5.17.2

package/README.md

@@ -26,7 +26,7 @@ Roles come from the bundled starter roles, `~/.pi/agent/pi-extensible-workflows/
 ## piewf
 
 ```sh
-piewf doctor [--role <role>] [--prompt <text>] [--json]
+piewf doctor [role|role-file] [--role <role>] [--prompt <text>] [--json]
 piewf doctor cleanup [--older-than-days <days>] [--yes]
 piewf inspect [session-id] [--json|--summary] [--failed]
 piewf transcript <session-file>

package/dist/src/cli.js

@@ -803,7 +803,7 @@ export async function runCli(args, options = {}, write = (text) => { process.std
     const stderr = options.stderr ?? ((text) => { process.stderr.write(text); });
     if (args[0] === "doctor" && args[1] !== "cleanup") {
         if (args.slice(1).some((arg) => arg === "--help" || arg === "-h")) {
-            write("Usage: piewf doctor [role] [--role <role>] [--prompt <text>] [--json]\n");
+            write("Usage: piewf doctor [role|role-file] [--role <role>] [--prompt <text>] [--json]\n");
             return 0;
         }
         try {
@@ -902,7 +902,7 @@ export async function runCli(args, options = {}, write = (text) => { process.std
             return 1;
         }
     }
-    write("Usage: piewf doctor [role] [--role <role>] [--prompt <text>] [--json] | inspect [session-id] [--json|--summary] [--failed] | transcript <session-file> | share <run-id> | bundle <workflow-name> [--name <command>] [--output <path>] [--force] | run <workflow-name> [workflow arguments] | run --script <path> [--name <workflow-name>] [--input <json>] | export <workflow-name> [--name <command>] [--output <path>] [--force] [--bundle]\n");
+    write("Usage: piewf doctor [role|role-file] [--role <role>] [--prompt <text>] [--json] | inspect [session-id] [--json|--summary] [--failed] | transcript <session-file> | share <run-id> | bundle <workflow-name> [--name <command>] [--output <path>] [--force] | run <workflow-name> [workflow arguments] | run --script <path> [--name <workflow-name>] [--input <json>] | export <workflow-name> [--name <command>] [--output <path>] [--force] [--bundle]\n");
     return 1;
 }
 if (process.argv[1] && sameFilesystemPath(fileURLToPath(import.meta.url), process.argv[1])) {

package/dist/src/doctor.js

@@ -1,5 +1,5 @@
-import { readFileSync, readdirSync, statSync } from "node:fs";
-import { basename, dirname, extname, join } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
 import { InMemoryCredentialStore, InMemoryModelsStore } from "@earendil-works/pi-ai";
 import { ModelRuntime, createAgentSessionFromServices, createAgentSessionServices, getAgentDir, hasTrustRequiringProjectResources, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { DEFAULT_SETTINGS, canonicalPath, createLocalPiSession, errorText, isNodeError, isObject, loadSettings, prepareAgentSetupForInspection, resolveAgentResourcePolicy, resolveWorkflowSettings, resolveModelReference, resourcePatternHasMagic, parseThinking, registeredWorkflowFunctions, registeredWorkflowRoleDirectoryRegistrations, workflowProjectSettingsPath, workflowSettingsPath, } from "pi-extensible-workflows";
@@ -207,10 +207,9 @@ function validateModel(value, known, available, source, diagnostics, aliases, dy
         diagnostics.push(diagnostic("error", "MODEL_INVALID", message, source, message.includes("thinking") ? THINKING_HINT : "Use provider/model:thinking."));
     }
 }
-function inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath, source) {
-    let definition;
+function parseRole(path, diagnostics, source) {
     try {
-        definition = parseRoleMarkdown(readFileSync(path, "utf8"), true, path);
+        return parseRoleMarkdown(readFileSync(path, "utf8"), true, path);
     }
     catch (error) {
         if (usesLegacyRoleSelectors(path)) {
@@ -221,6 +220,8 @@ function inspectRole(path, activeTools, knownModels, availableModels, diagnostic
         diagnostics.push(diagnostic("error", "ROLE_FRONTMATTER", source ? `${roleProvenance(source)} contains invalid role at "${path}": ${message}` : message, path, "Fix the role YAML frontmatter."));
         return undefined;
     }
+}
+function inspectRoleUsage(path, definition, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath) {
     const toolSelectorDiagnostic = positiveOnlyToolSelectorDiagnostic(path, definition.tools);
     if (toolSelectorDiagnostic)
         diagnostics.push(toolSelectorDiagnostic);
@@ -236,8 +237,13 @@ function inspectRole(path, activeTools, knownModels, availableModels, diagnostic
     for (const selector of definition.tools ?? []) {
         const tool = selector.startsWith("!") ? selector.slice(1) : selector;
         if (!selector.startsWith("!") && !resourcePatternHasMagic(selector) && !activeTools.has(tool))
-            diagnostics.push(diagnostic("error", "ROLE_TOOL_INACTIVE", `Tool is unknown or inactive: ${tool}`, path, "Use a tool listed under Pi active tools or enable its Pi extension."));
+            diagnostics.push(diagnostic("warning", "ROLE_TOOL_INACTIVE", `Tool is not in Pi's headless active tool list: ${tool}`, path, "Doctor cannot see tools that extensions add when a session starts; otherwise use a tool listed under Pi active tools or enable its Pi extension."));
     }
+}
+function inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath, source) {
+    const definition = parseRole(path, diagnostics, source);
+    if (definition)
+        inspectRoleUsage(path, definition, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath);
     return definition;
 }
 function matchResourcePolicy(policy, pi) {
@@ -435,15 +441,13 @@ export async function doctor(options = {}) {
         const starterPath = starterOverrides.get(file.path);
         const overriddenBy = starterOverriddenBy.get(file.path);
         roles.push({ name: file.name, path: file.path, scope: "extension", active: overriddenBy === undefined, extension: file.extension, ...(starterPath ? { overrides: starterPath } : {}), ...(overriddenBy ? { overriddenBy } : {}) });
-        const definition = inspectRole(file.path, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath, { directory: file.directory, extension: file.extension });
-        if (definition)
-            validateDoctorExtensionSettings(registry, mergeWorkflowExtensionSettings(settings.extensionSettings, definition.extensionSettings), "role", cwd, pi.trust.trusted, file.path, diagnostics, file.name);
+        const definition = parseRole(file.path, diagnostics, { directory: file.directory, extension: file.extension });
         if (duplicateExtensionNames.has(file.name))
             continue;
         if (extensionPaths.get(file.name) !== file.path)
             continue;
         if (definition)
-            definitions.set(file.name, definition);
+            definitions.set(file.name, { path: file.path, definition });
     }
     const globalPaths = new Map();
     const globalRoleDirs = workflowRoleDirectories(agentDir);
@@ -459,11 +463,9 @@ export async function doctor(options = {}) {
                 extension.overriddenBy = path;
             }
         }
-        const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath);
-        if (definition)
-            validateDoctorExtensionSettings(registry, mergeWorkflowExtensionSettings(settings.extensionSettings, definition.extensionSettings), "role", cwd, pi.trust.trusted, path, diagnostics, name);
+        const definition = parseRole(path, diagnostics);
         if (definition)
-            definitions.set(name, definition);
+            definitions.set(name, { path, definition });
         else
             definitions.delete(name);
     }
@@ -490,24 +492,49 @@ export async function doctor(options = {}) {
                 extension.overriddenBy = path;
             }
         }
-        const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath);
+        const definition = parseRole(path, diagnostics);
         if (definition)
-            validateDoctorExtensionSettings(registry, mergeWorkflowExtensionSettings(settings.extensionSettings, definition.extensionSettings), "role", cwd, pi.trust.trusted, path, diagnostics, name);
-        if (definition)
-            definitions.set(name, definition);
+            definitions.set(name, { path, definition });
         else
             definitions.delete(name);
     }
+    for (const [name, { path, definition }] of definitions) {
+        inspectRoleUsage(path, definition, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath);
+        validateDoctorExtensionSettings(registry, mergeWorkflowExtensionSettings(settings.extensionSettings, definition.extensionSettings), "role", cwd, pi.trust.trusted, path, diagnostics, name);
+    }
     const rolePaths = new Set(roles.map(({ path }) => path));
     if (diagnostics.some(({ code, source }) => source !== undefined && rolePaths.has(source) && (code === "ROLE_FRONTMATTER" || code === "AGENT_RESOURCE_SELECTOR_MIGRATION")))
         diagnostics.push(diagnostic("error", "ROLE_LOAD_BLOCKED", "Workflow role loading is blocked because the runtime rejects the complete role set when any active role file is invalid.", undefined, "Fix the reported role file before launching workflows."));
     let roleInspection;
     if (options.role !== undefined) {
-        const activeRole = roles.find(({ name, active }) => name === options.role && active);
-        const definition = activeRole ? definitions.get(options.role) : undefined;
-        if (!activeRole || !definition)
-            diagnostics.push(diagnostic("error", "ROLE_NOT_FOUND", `Active role not found: ${options.role}`, options.role));
+        let target;
+        //NOTE: installed role names drop ".md", so a target ending in ".md" is a role file path.
+        if (options.role.endsWith(".md")) {
+            const path = resolve(cwd, options.role);
+            if (!existsSync(path) || !statSync(path).isFile())
+                diagnostics.push(diagnostic("error", "ROLE_FILE_NOT_FOUND", `Role file not found: ${path}`, path));
+            else {
+                const name = basename(path, ".md");
+                const found = [];
+                const definition = inspectRole(path, activeTools, knownModels, availableModels, found, aliases, dynamicAliases, settingsPath);
+                if (definition)
+                    validateDoctorExtensionSettings(registry, mergeWorkflowExtensionSettings(settings.extensionSettings, definition.extensionSettings), "role", cwd, pi.trust.trusted, path, found, name);
+                // Discovery already reported an installed file; add only what is new.
+                const known = new Set(diagnostics.map((item) => JSON.stringify(item)));
+                diagnostics.push(...found.filter((item) => !known.has(JSON.stringify(item))));
+                if (definition)
+                    target = { name, path, definition };
+            }
+        }
         else {
+            const effective = definitions.get(options.role);
+            if (!effective)
+                diagnostics.push(diagnostic("error", "ROLE_NOT_FOUND", `Active role not found: ${options.role}`, options.role));
+            else
+                target = { name: options.role, ...effective };
+        }
+        if (target) {
+            const { name, path, definition } = target;
             const rootReference = pi.model ? `${pi.model.provider}/${pi.model.model}` : pi.availableModels[0] ?? pi.knownModels[0];
             if (!rootReference)
                 diagnostics.push(diagnostic("error", "ROLE_INSPECTION_MODEL", "Cannot inspect a role because Pi has no registered model"));
@@ -525,12 +552,12 @@ export async function doctor(options = {}) {
                         const dynamic = await registry.resolveModelAliases({ cwd, projectTrusted: pi.trust.trusted, rootModel, knownModels, availableModels, signal: new AbortController().signal });
                         roleAliases = { ...aliases, ...dynamic };
                     }
-                    roleInspection = await inspectRoleSession(cwd, agentDir, options.role, definition, activeRole.path, resourcePolicy, rootModel, [...activeTools], roleAliases, knownModels, availableModels, settingsPath, settings.extensionSettings, options.prompt ?? "", registry.agentSetupHooks(), diagnostics);
+                    roleInspection = await inspectRoleSession(cwd, agentDir, name, definition, path, resourcePolicy, rootModel, [...activeTools], roleAliases, knownModels, availableModels, settingsPath, settings.extensionSettings, options.prompt ?? "", registry.agentSetupHooks(), diagnostics);
                     if (roleInspection)
                         diagnostics.push(...roleInspection.setup.diagnostics);
                 }
                 catch (error) {
-                    diagnostics.push(diagnostic("error", "ROLE_INSPECTION_MODEL", errorText(error), activeRole.path));
+                    diagnostics.push(diagnostic("error", "ROLE_INSPECTION_MODEL", errorText(error), path));
                 }
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piewf/cli",
-  "version": "5.17.1",
+  "version": "5.17.2",
   "description": "CLI for pi-extensible-workflows",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": {
@@ -45,7 +45,7 @@
     "@earendil-works/pi-coding-agent": "0.85.0",
     "@earendil-works/pi-server": "0.85.0",
     "@earendil-works/pi-tui": "0.85.0",
-    "pi-extensible-workflows": "5.17.1",
+    "pi-extensible-workflows": "5.17.2",
     "typebox": "1.3.7"
   },
   "publishConfig": {