@piewf/cli 5.13.0 → 5.13.1

package/dist/src/bundles.d.ts

@@ -1,7 +1,11 @@
 import type { AgentDefinition, WorkflowCatalogFunction } from "pi-extensible-workflows";
+export interface PortableWorkflowSource {
+    module: string;
+    export: string;
+}
 export interface PortableWorkflowManifest {
     format: "pi-extensible-workflows-bundle";
-    version: 1;
+    version: 1 | 2;
     command: string;
     workflow: {
         name: string;
@@ -21,6 +25,11 @@ export interface PortableWorkflowManifest {
         environment: readonly string[];
     };
     aliasTargets?: Readonly<Record<string, string>>;
+    source?: Readonly<PortableWorkflowSource>;
+    bundler?: {
+        esbuild: string;
+    };
+    dependencies?: readonly string[];
     payload?: {
         extensions?: readonly string[];
         skills?: readonly string[];
@@ -38,7 +47,8 @@ export interface PortableWorkflowBundleInput {
     destination: string;
     command: string;
     workflow: WorkflowCatalogFunction;
-    functionSource: string;
+    source: PortableWorkflowSource;
+    dependencies?: readonly string[];
     piVersion?: string;
     engineVersion?: string;
     force?: boolean;
@@ -49,5 +59,4 @@ export interface PortableWorkflowBundleInput {
 }
 export declare function portableEngineVersion(): string;
 export declare function portablePiVersion(): string;
-export declare function normalizePortableFunctionSource(functionSource: string): string;
-export declare function writePortableWorkflowBundle(input: PortableWorkflowBundleInput): PortableWorkflowManifest;
+export declare function writePortableWorkflowBundle(input: PortableWorkflowBundleInput): Promise<PortableWorkflowManifest>;

package/dist/src/bundles.js

@@ -1,7 +1,9 @@
 import { chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
+import { builtinModules } from "node:module";
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
 function isJsonObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -316,42 +318,147 @@ function runnerSource() {
         "}",
     ].join("\n") + "\n";
 }
-export function normalizePortableFunctionSource(functionSource) {
-    const source = functionSource.trim();
-    if (!source || source.includes("[native code]"))
-        throw new Error("Workflow function source is unavailable");
-    if (/^(async\s+)?run\s*\(/.test(source))
-        return source.replace(/^(async\s+)?run\s*\(/, "$1function run(");
-    if (/^\*\s*run\s*\(/.test(source))
-        return source.replace(/^\*\s*run\s*\(/, "function* run(");
-    return source;
-}
-function workflowModule(workflow, functionSource, withRoles, aliasTargets, extensionModules) {
+function bundledWorkflowModule(workflow, source, withRoles, aliasTargets, extensionModules) {
     const aliases = Object.entries(aliasTargets);
-    const source = normalizePortableFunctionSource(functionSource);
+    const modules = ["./extension.mjs", ...extensionModules.map((name) => `./extensions/${name}`)];
     return [
-        `const run = ${source};`,
         "export async function register(registerWorkflowExtension) {",
-        ...extensionModules.map((name, index) => `  const extension${String(index)} = await import(${JSON.stringify(`./extensions/${name}`)});`),
-        ...extensionModules.map((_name, index) => `  if (typeof extension${String(index)}.default === "function") await extension${String(index)}.default();`),
+        "  const captured = [];",
+        "  const previousCapture = globalThis.__pi_bundle_capture;",
+        "  globalThis.__pi_bundle_capture = (extension) => { captured.push(extension); };",
+        "  try {",
+        ...modules.map((name, index) => `    const extension${String(index)} = await import(${JSON.stringify(name)});`),
+        `    const factory = extension0[${JSON.stringify(source.export)}];`,
+        `    if (typeof factory !== "function") throw new Error(${JSON.stringify(`Workflow extension export ${source.export} is not a function`)});`,
+        "    await factory();",
+        ...modules.slice(1).map((_name, index) => `    if (typeof extension${String(index + 1)}.default === "function") await extension${String(index + 1)}.default();`),
+        "  } finally {",
+        "    if (previousCapture === undefined) delete globalThis.__pi_bundle_capture; else globalThis.__pi_bundle_capture = previousCapture;",
+        "  }",
+        `  const extension = captured.find((candidate) => candidate?.functions?.[${JSON.stringify(workflow.name)}]);`,
+        `  if (!extension) throw new Error("Bundled extension does not register workflow ${workflow.name}");`,
+        "  for (const candidate of captured) if (candidate !== extension) registerWorkflowExtension(candidate);",
         "  registerWorkflowExtension({",
-        `    version: ${JSON.stringify("1.0.0")},`,
-        `    headline: ${JSON.stringify("Portable workflow bundle")},`,
-        ...(withRoles ? [`    roleDirectories: [new URL("./roles", import.meta.url)],`] : []),
-        ...(aliases.length ? [`    modelAliases: { ${aliases.map(([name, target]) => `${JSON.stringify(name)}: { resolve: () => ${JSON.stringify(target)} }`).join(", ")} },`] : []),
-        "    functions: {",
-        `      [${JSON.stringify(workflow.name)}]: {`,
-        `        description: ${JSON.stringify(workflow.description)},`,
-        `        input: ${JSON.stringify(workflow.input)},`,
-        `        output: ${JSON.stringify(workflow.output)},`,
-        "        run,",
-        "      },",
-        "    },",
+        "    ...extension,",
+        "    source: new URL(\"./extension.mjs\", import.meta.url).href,",
+        ...(aliases.length ? [`    modelAliases: { ...(extension.modelAliases ?? {}), ${aliases.map(([name, target]) => `${JSON.stringify(name)}: { resolve: () => ${JSON.stringify(target)} }`).join(", ")} },`] : []),
+        `    functions: { [${JSON.stringify(workflow.name)}]: extension.functions[${JSON.stringify(workflow.name)}] },`,
+        `    roleDirectories: ${withRoles ? "[new URL(\"./roles\", import.meta.url)]" : "[]"},`,
         "  });",
         "}",
         "",
     ].join("\n");
 }
+const nodeBuiltins = new Set(builtinModules);
+function packageName(specifier) {
+    const parts = specifier.split("/");
+    return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0] ?? specifier;
+}
+function isPackageSpecifier(specifier) {
+    return !specifier.startsWith(".") && !specifier.startsWith("/") && !specifier.startsWith("#") && !specifier.startsWith("node:") && !specifier.includes(":");
+}
+function isAllowedExternal(specifier) {
+    return nodeBuiltins.has(specifier) || packageName(specifier) === "pi-extensible-workflows";
+}
+const packageNamePattern = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+async function loadEsbuild() {
+    let modulePath;
+    try {
+        modulePath = createRequire(join(process.cwd(), "package.json")).resolve("esbuild");
+    }
+    catch (error) {
+        throw new Error("Portable workflow bundling requires optional esbuild. Install esbuild in the project where you run piewf bundle, for example with `npm install --save-dev esbuild`, and retry.", { cause: error });
+    }
+    try {
+        const loaded = await import(pathToFileURL(modulePath).href);
+        return loaded;
+    }
+    catch (error) {
+        throw new Error("Portable workflow bundling could not load esbuild from the current project. Install it with `npm install --save-dev esbuild` and retry.", { cause: error });
+    }
+}
+function sourceModulePath(source) {
+    try {
+        const url = new URL(source);
+        if (url.protocol !== "file:")
+            throw new Error("only file URLs are supported");
+        return fileURLToPath(url);
+    }
+    catch (error) {
+        throw new Error(`Workflow source must be a file URL: ${source}`, { cause: error });
+    }
+}
+function dependencyNames(dependencies) {
+    const rawDependencies = dependencies;
+    if (rawDependencies !== undefined && !Array.isArray(rawDependencies))
+        throw new Error("Workflow bundle dependencies must be non-empty package names");
+    const values = dependencies ?? [];
+    if (values.some((dependency) => typeof dependency !== "string" || !dependency.trim()))
+        throw new Error("Workflow bundle dependencies must be non-empty package names");
+    const names = [...new Set(values.map((dependency) => dependency.trim()))];
+    if (names.some((dependency) => !packageNamePattern.test(dependency)))
+        throw new Error("Workflow bundle dependencies must be package names");
+    return names.sort();
+}
+function isBuildFailure(error) {
+    return error instanceof Error && Array.isArray(error.errors);
+}
+function bundleFailure(error) {
+    if (!isBuildFailure(error))
+        return error instanceof Error ? error : new Error(String(error));
+    const dynamicImport = error.errors.find((message) => message.id === "unsupported-dynamic-import");
+    if (!dynamicImport)
+        return error;
+    const file = dynamicImport.location ? resolve(dynamicImport.location.file) : "the workflow extension";
+    return new Error(`Unsupported dynamic import in ${file}: dynamic imports must use a string-literal module path, otherwise the module is not bundleable`, { cause: error });
+}
+async function bundleExtension(sourcePath, sourceExport, dependencies) {
+    const esbuild = await loadEsbuild();
+    const undeclared = new Set();
+    const result = await esbuild.build({
+        entryPoints: [sourcePath],
+        bundle: true,
+        format: "esm",
+        platform: "node",
+        nodePaths: [
+            join(process.cwd(), "node_modules"),
+            join(dirname(fileURLToPath(import.meta.url)), "../../node_modules"),
+            join(dirname(fileURLToPath(import.meta.url)), "../../../node_modules"),
+            join(dirname(fileURLToPath(import.meta.url)), "../../../../node_modules"),
+        ],
+        write: false,
+        metafile: true,
+        logLevel: "silent",
+        logOverride: { "unsupported-dynamic-import": "error" },
+        plugins: [{
+                name: "portable-workflow-dependencies",
+                setup(build) {
+                    build.onResolve({ filter: /.*/ }, (args) => {
+                        if (!isPackageSpecifier(args.path))
+                            return undefined;
+                        const name = packageName(args.path);
+                        if (isAllowedExternal(args.path))
+                            return { path: args.path, external: true };
+                        if (name.startsWith("@earendil-works/"))
+                            return { errors: [{ text: `Pi packages (@earendil-works/*) cannot be bundled; use the pi-extensible-workflows API instead: ${name}` }] };
+                        if (dependencies.includes(name))
+                            return undefined;
+                        undeclared.add(name);
+                        return { path: args.path, external: true };
+                    });
+                },
+            }],
+    }).catch((error) => { throw bundleFailure(error); });
+    if (undeclared.size)
+        throw new Error(`Undeclared dependencies: ${[...undeclared].sort().join(", ")}`);
+    const output = result.outputFiles[0];
+    if (!output)
+        throw new Error("esbuild produced no workflow extension output");
+    const exports = Object.values(result.metafile.outputs).flatMap(({ exports: names }) => names);
+    if (!exports.includes(sourceExport))
+        throw new Error(`Bundled workflow extension does not export ${sourceExport}`);
+    return { source: output.text, esbuild: esbuild.version };
+}
 function roleMarkdown(role) {
     const metadata = ["---"];
     if (role.description !== undefined)
@@ -413,13 +520,16 @@ function copyResources(root, resources) {
     copy("dependencies", resources.dependencies);
     return Object.keys(payload).length ? payload : undefined;
 }
-function extensionPackageShim(paths) {
+function extensionPackageShim(paths, bundledSource) {
     const importedNames = new Set();
-    for (const path of paths) {
+    const sources = paths.map((path) => {
         if (!/\.(?:c|m)?js$/.test(path))
             throw new Error(`Selected extension must be a JavaScript module file: ${path}`);
-        const source = readFileSync(path, "utf8");
-        for (const match of source.matchAll(/import\s*\{([^}]+)\}\s*from\s*["']pi-extensible-workflows["']/g)) {
+        return readFileSync(path, "utf8");
+    });
+    sources.push(bundledSource);
+    for (const source of sources) {
+        for (const match of source.matchAll(/import\s+(?:type\s+)?\{([^}]+)\}\s+from\s+["']pi-extensible-workflows["']/g)) {
             for (const part of (match[1] ?? "").split(",")) {
                 const imported = part.trim().split(/\s+as\s+/, 1)[0]?.trim();
                 if (imported && /^[A-Za-z_$][\w$]*$/.test(imported))
@@ -427,13 +537,13 @@ function extensionPackageShim(paths) {
             }
         }
     }
-    return [...importedNames].map((name) => `export const ${name} = globalThis.__pi_bundle_api.${name};`).join("\n") + "\n";
+    return [...importedNames].map((name) => name === "registerWorkflowExtension" ? "export const registerWorkflowExtension = (extension) => globalThis.__pi_bundle_capture ? globalThis.__pi_bundle_capture(extension) : globalThis.__pi_bundle_api.registerWorkflowExtension(extension);" : `export const ${name} = globalThis.__pi_bundle_api.${name};`).join("\n") + "\n";
 }
-export function writePortableWorkflowBundle(input) {
+function baseManifest(input, version) {
     const engineVersion = input.engineVersion ?? portableEngineVersion();
-    const manifest = {
+    return {
         format: "pi-extensible-workflows-bundle",
-        version: 1,
+        version,
         command: input.command,
         workflow: { name: input.workflow.name, description: input.workflow.description, input: input.workflow.input, output: input.workflow.output },
         runtime: { pi: input.piVersion?.trim() || "unknown", "@piewf/cli": engineVersion.trim() || "unknown" },
@@ -446,6 +556,8 @@ export function writePortableWorkflowBundle(input) {
         },
         ...(input.aliasTargets && Object.keys(input.aliasTargets).length ? { aliasTargets: Object.freeze({ ...input.aliasTargets }) } : {}),
     };
+}
+function writeBundleFiles(input, manifest, workflowSource, bundledExtensionSource) {
     const parent = dirname(input.destination);
     mkdirSync(parent, { recursive: true });
     if (existsSync(input.destination) && !input.force)
@@ -468,15 +580,13 @@ export function writePortableWorkflowBundle(input) {
         if (copiedPayload)
             manifest.payload = copiedPayload;
         const extensionPaths = input.resources?.extensions ?? [];
-        const extensionModules = extensionPaths.map((source) => basename(source));
-        if (extensionPaths.length) {
-            const packageDirectory = join(payload, "node_modules", "pi-extensible-workflows");
-            mkdirSync(packageDirectory, { recursive: true });
-            writeFileSync(join(packageDirectory, "package.json"), '{"type":"module","exports":"./index.mjs"}\n', { encoding: "utf8", mode: 0o600 });
-            writeFileSync(join(packageDirectory, "index.mjs"), extensionPackageShim(extensionPaths), { encoding: "utf8", mode: 0o600 });
-        }
+        writeFileSync(join(payload, "extension.mjs"), bundledExtensionSource, { encoding: "utf8", mode: 0o600 });
+        const packageDirectory = join(payload, "node_modules", "pi-extensible-workflows");
+        mkdirSync(packageDirectory, { recursive: true });
+        writeFileSync(join(packageDirectory, "package.json"), '{"type":"module","exports":"./index.mjs"}\n', { encoding: "utf8", mode: 0o600 });
+        writeFileSync(join(packageDirectory, "index.mjs"), extensionPackageShim(extensionPaths, bundledExtensionSource), { encoding: "utf8", mode: 0o600 });
         writeFileSync(join(temporary, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-        writeFileSync(join(payload, "workflow.mjs"), workflowModule(input.workflow, input.functionSource, Object.keys(roles).length > 0, input.aliasTargets ?? {}, extensionModules), { encoding: "utf8", mode: 0o600 });
+        writeFileSync(join(payload, "workflow.mjs"), workflowSource, { encoding: "utf8", mode: 0o600 });
         writeFileSync(join(payload, "runner.mjs"), runnerSource(), { encoding: "utf8", mode: 0o700 });
         const launcher = join(temporary, input.command);
         writeFileSync(launcher, shellLauncher(), { encoding: "utf8", mode: 0o755 });
@@ -491,3 +601,12 @@ export function writePortableWorkflowBundle(input) {
     }
     return manifest;
 }
+export async function writePortableWorkflowBundle(input) {
+    if (typeof input.source.export !== "string" || !input.source.export.trim())
+        throw new Error("Workflow source export must be a non-empty name");
+    const sourcePath = sourceModulePath(input.source.module);
+    const dependencies = dependencyNames(input.dependencies);
+    const bundled = await bundleExtension(sourcePath, input.source.export, dependencies);
+    const manifest = { ...baseManifest(input, 2), source: Object.freeze({ module: basename(sourcePath), export: input.source.export }), bundler: { esbuild: bundled.esbuild }, dependencies: Object.freeze([...dependencies]) };
+    return writeBundleFiles(input, manifest, bundledWorkflowModule(input.workflow, input.source, Object.keys(input.roles ?? {}).length > 0, input.aliasTargets ?? {}, input.resources?.extensions?.map((source) => basename(source)) ?? []), bundled.source);
+}

package/dist/src/cli.js

@@ -8,7 +8,7 @@ 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, registeredWorkflowFunctions, truncateWorkflowProgress, workflowCatalog, workflowSettingsPath } from "pi-extensible-workflows";
+import workflowExtension, { errorText, formatWorkflowProgress, isNodeError, jsonValue, loadAgentDefinitions, registeredWorkflowFunctionSources, truncateWorkflowProgress, workflowCatalog, workflowSettingsPath } from "pi-extensible-workflows";
 import { portableEngineVersion, portablePiVersion, writePortableWorkflowBundle } from "./bundles.js";
 import { runSessionInspector, transcriptFileLines } from "./session-inspector.js";
 import { isPersistedRun, listPersistedSessionIds, listRunIds } from "pi-extensible-workflows/persistence";
@@ -777,9 +777,9 @@ async function bundleWorkflowCli(rawArgs, options) {
         const fn = runtime.catalog.functions.find((candidate) => candidate.name === workflowName);
         if (!fn)
             throw new Error(`Unknown workflow function: ${workflowName}`);
-        const registered = registeredWorkflowFunctions()[workflowName];
-        if (!registered)
-            throw new Error(`Workflow ${workflowName} is not exportable because its registered implementation is unavailable`);
+        const source = registeredWorkflowFunctionSources()[workflowName];
+        if (!source)
+            throw new Error(`Workflow ${workflowName} is not exportable; add \`source: import.meta.url\` to extension ${fn.headline}`);
         const definitions = requirements.roles.length ? loadAgentDefinitions(options.cwd ?? process.cwd(), options.agentDir ?? getAgentDir(), runtime.services.settingsManager.isProjectTrusted()) : {};
         const roles = Object.fromEntries(requirements.roles.map((role) => {
             if (!role || role === "." || role === ".." || role.includes("/") || role.includes("\\"))
@@ -798,7 +798,7 @@ async function bundleWorkflowCli(rawArgs, options) {
             return typeof target === "string" ? [[name, target]] : [];
         }));
         const selectedResources = Object.values(resources).some((entries) => entries.length) ? resources : undefined;
-        writePortableWorkflowBundle({ destination, command, workflow: fn, functionSource: registered.run.toString(), requirements, aliasTargets, roles, ...(selectedResources ? { resources: selectedResources } : {}), piVersion: portablePiVersion(), engineVersion: portableEngineVersion(), force });
+        await writePortableWorkflowBundle({ destination, command, workflow: fn, source: { module: source.module, export: source.export }, dependencies: source.dependencies, requirements, aliasTargets, roles, ...(selectedResources ? { resources: selectedResources } : {}), piVersion: portablePiVersion(), engineVersion: portableEngineVersion(), force });
         options.write(`Bundled ${workflowName} at ${destination}\n`);
         options.write(`Run ${join(destination, command)} setup before launching the workflow.\n`);
         return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piewf/cli",
-  "version": "5.13.0",
+  "version": "5.13.1",
   "description": "CLI for pi-extensible-workflows",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": {
@@ -29,6 +29,7 @@
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@types/node": "24.12.4",
+    "esbuild": "^0.28.2",
     "eslint": "10.0.3",
     "typescript": "5.9.3",
     "typescript-eslint": "8.63.0"
@@ -42,7 +43,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.13.0",
+    "pi-extensible-workflows": "5.13.1",
     "typebox": "1.3.7"
   },
   "publishConfig": {