@marcoscale98/piewf-cli 5.14.1-fork.1 → 5.17.0-fork.1

package/README.md

@@ -0,0 +1,43 @@
+# @marcoscale98/piewf-cli
+
+Terminal commands for [pi-extensible-workflows](https://github.com/vekexasia/pi-extensible-workflows): `pi-role` starts Pi as a role, `piewf` operates workflows.
+
+Requires Node.js 22.19 or newer and the `pi` command on `PATH`. This is trusted host code with the same filesystem and process access as Pi.
+
+```sh
+npm install --global @marcoscale98/piewf-cli@fork
+```
+
+## pi-role
+
+Start a regular Pi session with a role's model, tools, skills, extensions, and system prompt. Everything after the role name goes to Pi unchanged.
+
+```sh
+pi-role                                    # list the available roles
+pi-role reviewer                           # interactive Pi as the reviewer role
+pi-role scout -p "Where is the retry logic?"   # one-shot prompt
+pi-role developer --continue               # resume the last session as the developer role
+pi-role reviewer --approve                 # trust the project so its roles and settings apply
+npx -p @marcoscale98/piewf-cli@fork pi-role oracle   # without installing
+```
+
+Roles come from the bundled starter roles, `~/.pi/agent/pi-extensible-workflows/roles/*.md`, and, in trusted projects, `.pi/pi-extensible-workflows/roles/*.md`. The [roles guide](https://vekexasia.github.io/pi-extensible-workflows/roles.html#pi-role) lists what each role field becomes on the Pi command line and the launcher's limits; the [role file reference](https://vekexasia.github.io/pi-extensible-workflows/roles.html#files) covers writing your own.
+
+## piewf
+
+```sh
+piewf doctor [--role <role>] [--prompt <text>] [--json]
+piewf doctor cleanup [--older-than-days <days>] [--yes]
+piewf inspect [session-id] [--json|--summary] [--failed]
+piewf transcript <session-file>
+piewf run <workflow-name> [workflow arguments]
+piewf run --script <workflow.js> [--name <workflow-name>] [--input <json>]
+piewf export <workflow-name> [--name <command>] [--output <path>] [--force]
+piewf bundle <workflow-name> [--name <command>] [--output <directory>] [--force]
+```
+
+See [CLI operations](https://vekexasia.github.io/pi-extensible-workflows/developers.html#operations).
+
+## License
+
+MIT

package/dist/src/cli.js

@@ -8,7 +8,8 @@ import { ProjectTrustStore, SessionManager, SettingsManager, createAgentSessionF
 import { Value } from "typebox/value";
 import { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";
 import { doctorCleanup, doctorCleanupExitCode, formatDoctorCleanupReport } from "./doctor-cleanup.js";
-import workflowExtension, { errorText, formatWorkflowProgress, isNodeError, jsonValue, loadAgentDefinitions, object, registeredWorkflowFunctionSources, sameFilesystemPath, truncateWorkflowProgress, workflowCatalog, workflowSettingsPath } from "@marcoscale98/pi-extensible-workflows";
+import { loadAgentDefinitions } from "@marcoscale98/pi-extensible-workflows/roles";
+import workflowExtension, { errorText, formatWorkflowProgress, isNodeError, jsonValue, object, registeredWorkflowFunctionSources, sameFilesystemPath, truncateWorkflowProgress, workflowCatalog, workflowSettingsPath } from "@marcoscale98/pi-extensible-workflows";
 import { CLI_PACKAGE_NAME, portableEngineVersion, portablePiVersion, writePortableWorkflowBundle } from "./bundles.js";
 import { runSessionInspector, transcriptFileLines } from "./session-inspector.js";
 import { isPersistedRun, listPersistedSessionIds, listRunIds } from "@marcoscale98/pi-extensible-workflows/persistence";

package/dist/src/doctor.js

@@ -2,7 +2,8 @@ import { readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, extname, join } 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, parseRoleMarkdown, registeredWorkflowFunctions, registeredWorkflowRoleDirectoryRegistrations, workflowRoleDirectories, workflowProjectSettingsPath, workflowSettingsPath, } from "@marcoscale98/pi-extensible-workflows";
+import { DEFAULT_SETTINGS, canonicalPath, createLocalPiSession, errorText, isNodeError, isObject, loadSettings, prepareAgentSetupForInspection, resolveAgentResourcePolicy, resolveWorkflowSettings, resolveModelReference, resourcePatternHasMagic, parseThinking, registeredWorkflowFunctions, registeredWorkflowRoleDirectoryRegistrations, workflowProjectSettingsPath, workflowSettingsPath, } from "@marcoscale98/pi-extensible-workflows";
+import { parseRoleMarkdown, workflowRoleDirectories } from "@marcoscale98/pi-extensible-workflows/roles";
 import { loadingRegistry } from "@marcoscale98/pi-extensible-workflows";
 import { selectResourcesByLayers, unmatchedResourcePatterns, mergeWorkflowExtensionSettings } from "@marcoscale98/pi-extensible-workflows";
 const THINKING_HINT = "Use off, minimal, low, medium, high, xhigh, or max.";
@@ -397,6 +398,7 @@ export async function doctor(options = {}) {
     ].sort((left, right) => left.name.localeCompare(right.name) || left.kind.localeCompare(right.kind));
     const roles = [];
     const definitions = new Map();
+    // Keep this scan local because doctor reports every invalid and duplicate file; discoverRoles intentionally fails closed on the complete set.
     const extensionScan = scanExtensionRoleFiles(registeredWorkflowRoleDirectoryRegistrations());
     for (const { registration, error } of extensionScan.errors) {
         const message = errorText(error);

package/dist/src/pi-role.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { type ResolvedRole } from "@marcoscale98/pi-extensible-workflows/roles";
+export declare function piArguments(role: ResolvedRole, skillPaths: ReadonlyMap<string, string>, rest: readonly string[]): string[];
+export declare function resolvePiArguments(name: string, rest: readonly string[], cwd?: string, agentDir?: string): Promise<string[]>;
+export declare function runPiRole(argv: readonly string[]): Promise<number>;

package/dist/src/pi-role.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { constants } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DefaultPackageManager, DefaultResourceLoader, ProjectTrustStore, SettingsManager, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { discoverRoles, loadRole, resolveRole } from "@marcoscale98/pi-extensible-workflows/roles";
+import { CONTEXT_FILE_SCOPES, WorkflowError, errorText, resourcePatternHasMagic, sameFilesystemPath } from "@marcoscale98/pi-extensible-workflows";
+// Pi builtin tools stand in for the workflow session boundary; extension tool names selected by the role pass through.
+const PI_BUILTIN_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+function starterRoleDirectories() {
+    const core = dirname(fileURLToPath(import.meta.resolve("@marcoscale98/pi-extensible-workflows")));
+    return [{ path: resolve(core, "../starter/roles"), extension: { version: "0.0.0", headline: "Starter roles" }, builtin: true }];
+}
+function projectTrust(cwd, agentDir, args) {
+    const end = args.indexOf("--");
+    const flag = args.slice(0, end < 0 ? args.length : end).filter((arg) => ["--approve", "-a", "--no-approve", "-na"].includes(arg)).at(-1); // last wins, as in pi
+    if (flag)
+        return flag === "--approve" || flag === "-a";
+    return new ProjectTrustStore(agentDir).get(cwd) ?? false; // no saved decision: project roles, settings, and resources stay out
+}
+export function piArguments(role, skillPaths, rest) {
+    const argv = [];
+    if (role.model)
+        argv.push("--model", `${role.model.provider}/${role.model.model}${role.model.thinking ? `:${role.model.thinking}` : ""}`);
+    if (role.selectorLayers.tools.some((layer) => layer !== undefined))
+        argv.push("--tools", (role.tools ?? []).join(","));
+    argv.push("--no-skills");
+    for (const name of role.selectedSkills ?? [])
+        argv.push("--skill", skillPaths.get(name) ?? name);
+    argv.push("--no-extensions");
+    for (const path of role.selectedExtensions ?? [])
+        argv.push("--extension", path);
+    if (role.systemPrompt.text)
+        argv.push(role.systemPrompt.mode === "override" ? "--system-prompt" : "--append-system-prompt", role.systemPrompt.text);
+    if (role.contextFiles !== undefined && new Set(role.contextFiles).size < CONTEXT_FILE_SCOPES.length) {
+        if (role.contextFiles.length > 0)
+            throw new Error(`Role ${role.name ?? ""} selects a subset of context file scopes (${role.contextFiles.join(", ")}); pi-role only supports all scopes or none`);
+        argv.push("--no-context-files");
+    }
+    return [...argv, ...rest];
+}
+export async function resolvePiArguments(name, rest, cwd = process.cwd(), agentDir = getAgentDir()) {
+    const projectTrusted = projectTrust(cwd, agentDir, rest);
+    const settingsManager = SettingsManager.create(cwd, agentDir, { projectTrusted: false });
+    settingsManager.setProjectTrusted(projectTrusted);
+    const discovered = await new DefaultPackageManager({ cwd, agentDir, settingsManager }).resolve();
+    const visible = ({ enabled, metadata }) => enabled && (projectTrusted || metadata.scope !== "project");
+    const extensions = [...new Set(discovered.extensions.filter(visible).map(({ path }) => path))];
+    const loader = new DefaultResourceLoader({ cwd, agentDir, settingsManager, noExtensions: true, noSkills: true, additionalSkillPaths: [...new Set(discovered.skills.filter(visible).map(({ path }) => path))] });
+    await loader.reload();
+    const skillPaths = new Map(loader.getSkills().skills.map(({ name: skill, filePath }) => [skill, filePath]));
+    const discovery = { cwd, agentDir, projectTrusted, extensionRoleDirectories: starterRoleDirectories() };
+    const resolveWith = (definition) => {
+        const requestedTools = resolveRole(name, { ...discovery, definition }).selectorLayers.tools.flatMap((layer) => layer ?? []).filter((selector) => !selector.startsWith("!") && !resourcePatternHasMagic(selector));
+        return resolveRole(name, { ...discovery, definition, resources: { extensions, skills: [...skillPaths.keys()], tools: [...new Set([...PI_BUILTIN_TOOLS, ...requestedTools])] } });
+    };
+    const definition = loadRole(name, discovery);
+    let role;
+    try {
+        role = resolveWith(definition);
+    }
+    catch (error) {
+        // Starter roles use aliases the workflow extension resolves against the launching session's model; standalone, pi's default model plays that part.
+        if (!(error instanceof WorkflowError) || error.code !== "UNKNOWN_MODEL")
+            throw error;
+        process.stderr.write(`pi-role: ${errorText(error)}; starting pi with its default model\n`);
+        const withoutModel = { ...definition };
+        delete withoutModel.model;
+        role = resolveWith(withoutModel);
+    }
+    return piArguments(role, skillPaths, rest);
+}
+function usage(cwd, agentDir) {
+    const roles = discoverRoles({ cwd, agentDir, projectTrusted: projectTrust(cwd, agentDir, []), extensionRoleDirectories: starterRoleDirectories() });
+    const lines = Object.entries(roles).map(([name, { description }]) => `  ${name.padEnd(16)}${description ?? ""}`);
+    return `Usage: pi-role <role> [pi arguments...]\n\nRoles:\n${lines.join("\n")}\n\nProject roles need pi's saved trust decision or --approve.\n`;
+}
+export async function runPiRole(argv) {
+    const [name, ...rest] = argv;
+    if (!name || name === "--help" || name === "-h") {
+        process.stdout.write(usage(process.cwd(), getAgentDir()));
+        return name ? 0 : 1;
+    }
+    let args;
+    try {
+        args = await resolvePiArguments(name, rest);
+    }
+    catch (error) {
+        process.stderr.write(`pi-role: ${errorText(error)}\n`);
+        return 1;
+    }
+    return new Promise((done) => {
+        const child = spawn("pi", args, { stdio: "inherit" });
+        process.on("SIGINT", () => { }); // the child owns the terminal; it handles Ctrl+C and exits
+        child.on("error", (error) => { process.stderr.write(`pi-role: ${errorText(error)}\n`); done(1); });
+        child.on("exit", (code, signal) => { done(signal ? 128 + constants.signals[signal] : code ?? 1); });
+    });
+}
+if (process.argv[1] && sameFilesystemPath(fileURLToPath(import.meta.url), process.argv[1])) {
+    process.exitCode = await runPiRole(process.argv.slice(2));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcoscale98/piewf-cli",
-  "version": "5.14.1-fork.1",
+  "version": "5.17.0-fork.1",
   "description": "CLI for pi-extensible-workflows",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": {
@@ -10,16 +10,18 @@
   },
   "type": "module",
   "exports": {
-    ".": "./dist/src/cli.js"
+    ".": "./dist/src/cli.js",
+    "./pi-role": "./dist/src/pi-role.js"
   },
   "bin": {
-    "piewf": "./dist/src/cli.js"
+    "piewf": "./dist/src/cli.js",
+    "pi-role": "./dist/src/pi-role.js"
   },
   "files": [
     "dist/src"
   ],
   "scripts": {
-    "build": "npm --prefix ../.. run build --workspace=../core && rm -rf dist && tsc -p tsconfig.json && chmod +x dist/src/cli.js",
+    "build": "npm --prefix ../.. run build --workspace=../core && rm -rf dist && tsc -p tsconfig.json && chmod +x dist/src/cli.js dist/src/pi-role.js",
     "inspect": "node dist/src/cli.js inspect",
     "test": "npm run build && TEST_FILES='dist/test/*.test.js' npm run test:run",
     "test:run": "files=${TEST_FILES:-dist/test/*.test.js}; printf '%s\\n' $files | xargs -n1 -P20 sh -c 'tmp=$(mktemp -d); TMPDIR=\"$tmp\" node --test --test-concurrency=1 --test-timeout=60000 --test-force-exit --test-reporter=dot \"$1\"; status=$?; rm -rf \"$tmp\"; exit $status' sh",
@@ -43,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",
-    "@marcoscale98/pi-extensible-workflows": "5.14.1-fork.1",
+    "@marcoscale98/pi-extensible-workflows": "5.17.0-fork.1",
     "typebox": "1.3.7"
   },
   "publishConfig": {