@piewf/cli 5.17.0 → 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-cleanup.js

@@ -3,7 +3,7 @@ import { lstat, readdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { AGENT_STATES as CORE_AGENT_STATES, BUDGET_DIMENSIONS as CORE_BUDGET_DIMENSIONS, BUDGET_EVENT_TYPES as CORE_BUDGET_EVENT_TYPES, HARD_TERMINAL_RUN_STATES, RUN_STATES, errorText, isNodeError, isThinkingLevel, jsonValue, object, validateBudget, validateModelAliases, validateSchema } from "pi-extensible-workflows";
-import { acquireSessionLease, hasLiveSessionLease, projectSessionsDirectory, RunStore } from "pi-extensible-workflows/persistence";
+import { acquireSessionLease, hasLiveSessionLease, json, projectSessionsDirectory, RunStore } from "pi-extensible-workflows/persistence";
 const DAY_MS = 24 * 60 * 60 * 1000;
 const REQUIRED_RUN_FILES = ["workflow.js", "state.json", "snapshot.json", "journal.json", "ownership.json", "worktrees.json", "borrowed-worktrees.json", "system-prompts.json"];
 const OPTIONAL_RUN_FILES = new Set(["result.json", "summary.json"]);
@@ -22,7 +22,6 @@ function positiveDays(value) { if (!Number.isSafeInteger(value) || value < 1 ||
     throw new Error("older-than-days must be a positive integer"); return value; }
 function runItem(entry, action, reason) { return { sessionId: entry.sessionId, runId: entry.runId, action, state: entry.run.state, stateMtimeMs: entry.stateMtimeMs, path: entry.store.directory, ...(reason ? { reason } : {}) }; }
 function sameNames(left, right) { return left.length === right.length && left.every((value, index) => value === right[index]); }
-async function jsonFile(path) { return JSON.parse(await readFile(path, "utf8")); }
 async function requiredFile(path) { const info = await lstat(path); if (!info.isFile())
     throw new Error(`Required artifact is not a regular file: ${path}`); }
 function stringList(value, label, nonEmpty = false) { if (!isList(value) || value.some((item) => typeof item !== "string" || (nonEmpty && !item)))
@@ -271,7 +270,7 @@ function validateJournal(value) { if (!object(value) || !object(value.completed)
     validateBudget(decision.proposed);
 } }
 async function validateSystemPrompts(store) {
-    const value = await jsonFile(store.systemPromptPath());
+    const value = await json(store.systemPromptPath());
     if (object(value) && value.version === 2) {
         await store.systemPrompts();
         return;
@@ -312,14 +311,14 @@ async function validateRunArtifacts(store, workflowScript, state) {
     if (await readFile(join(store.directory, "workflow.js"), "utf8") !== workflowScript)
         throw new Error("Persisted workflow source does not match its launch snapshot");
     await validateSystemPrompts(store);
-    const result = await jsonFile(join(store.directory, "result.json")).catch((error) => { if (isNodeError(error, "ENOENT"))
+    const result = await json(join(store.directory, "result.json")).catch((error) => { if (isNodeError(error, "ENOENT"))
         return undefined; throw error; });
     if (result === undefined && state === "completed")
         throw new Error("Completed run result is missing");
     if (result !== undefined && !jsonValue(result))
         throw new Error("Persisted workflow result is invalid");
-    validateJournal(await jsonFile(join(store.directory, "journal.json")));
-    const rawOwnership = await jsonFile(join(store.directory, "ownership.json"));
+    validateJournal(await json(join(store.directory, "journal.json")));
+    const rawOwnership = await json(join(store.directory, "ownership.json"));
     if (!isList(rawOwnership))
         throw new Error("Persisted ownership records are invalid");
     const ownershipIds = new Set();
@@ -362,7 +361,7 @@ async function scanSession(cwd, sessionId, home, expectedLease) {
     const ownerPath = join(runsPath, "owner.json");
     let liveLease = false;
     if (expectedLease && expectedLease.path === ownerPath) {
-        const owned = await jsonFile(ownerPath);
+        const owned = await json(ownerPath);
         if (!object(owned) || owned.token !== expectedLease.token)
             throw new Error("Session ownership lease changed before deletion");
     }

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/dist/src/session-inspector.js

@@ -113,7 +113,8 @@ function transcript(manager) {
 }
 function readTranscript(path) {
     try {
-        if (!existsSync(path) || !statSync(path).isFile() || statSync(path).size === 0)
+        const info = existsSync(path) ? statSync(path) : undefined;
+        if (!info?.isFile() || info.size === 0)
             return undefined;
         const manager = SessionManager.open(path);
         if (!manager.getHeader())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piewf/cli",
-  "version": "5.17.0",
+  "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.0",
+    "pi-extensible-workflows": "5.17.2",
     "typebox": "1.3.7"
   },
   "publishConfig": {