@amaster.ai/runtime-cli 1.1.14-beta.0 → 1.1.14-beta.1

package/README.md

@@ -9,7 +9,7 @@ CLI for Amaster SDK - Multi-app support for OpenClaw. Manage multiple Amaster ap
 - **Structured Output**: `json`, `pretty`, `table`, `ndjson`, and `csv`
 - **Entity Management**: CRUD, options lookup, and bulk operations on entities
 - **BPM**: Manage Camunda processes, tasks, and instances
-- **Workflow**: Run workflows
+- **Workflow**: Discover, inspect, and run workflows
 - **S3 Storage**: Upload files, download objects, and inspect metadata
 - **OpenClaw Integration**: Initialize app-specific skills and MCP servers
 
@@ -86,6 +86,10 @@ amaster logout --app myapp
 ### 4. Use SDK Features
 
 ```bash
+# Discover runnable workflows and inspect required inputs
+amaster workflow list --app myapp --format pretty
+amaster workflow get <workflow-app-id> --app myapp --format pretty
+
 # Run an anonymous workflow when the app exposes it publicly
 amaster workflow run text-sentiment-analysis --app myapp \
   --input '{"input_text":"I love this product. It is fast and easy to use."}'
@@ -639,6 +643,15 @@ amaster bpm modify-instance proc-123 --app myapp \
 ### Workflow
 
 ```bash
+amaster workflow list [options]          # List workflow apps and runnable names
+  --app <app-code>                    # App code (uses default if not specified)
+  --page <n>                          # Page number
+  --limit <n>                         # Page size
+  --mode <mode>                       # workflow | chat | completion | agent-chat
+
+amaster workflow get <id> [options]     # Get workflow details and input variables by workflow app ID
+  --app <app-code>                    # App code (uses default if not specified)
+
 amaster workflow run <name> [options]    # Run a workflow
   --app <app-code>                    # App code (uses default if not specified)
   -i, --input <json>                  # Workflow inputs object as JSON or @file
@@ -649,6 +662,8 @@ amaster workflow run <name> [options]    # Run a workflow
   --trace-id <traceId>                # Workflow trace ID
 ```
 
+Use `workflow list` to discover workflow app IDs and `runnable_name`. Use the `id` with `workflow get`, and use the `runnable_name` or the `name` returned by `workflow get` with `workflow run`.
+
 ### S3 Storage
 
 ```bash

package/dist/cli.cjs

@@ -2267,6 +2267,8 @@ async function getUserRoles(client, options) {
     exitWithCommandError3(spinner, "Failed to fetch user roles", error);
   }
 }
+var WORKFLOW_LIST_PATH = "/api/proxy/builtin/platform/workflow/openapi/apps";
+var WORKFLOW_GET_PATH = (workflowId) => `/api/proxy/builtin/platform/workflow/openapi/apps/${encodeURIComponent(workflowId)}/dsl`;
 function resolveInputSource4(input) {
   if (!input.startsWith("@")) {
     return input;
@@ -2292,6 +2294,151 @@ function parseJsonInput3(input, label) {
 function isPlainObject4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function parseWorkflowTracing(value) {
+  if (!value) {
+    return null;
+  }
+  if (isPlainObject4(value)) {
+    return value;
+  }
+  if (typeof value !== "string") {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(value);
+    return isPlainObject4(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function getRunnableName(summary) {
+  const tracing = parseWorkflowTracing(summary.tracing);
+  const baseName = tracing?.base_name;
+  if (typeof baseName === "string" && baseName.trim()) {
+    return baseName.trim();
+  }
+  return null;
+}
+function normalizeWorkflowSummary(summary) {
+  return {
+    ...summary,
+    id: typeof summary.id === "string" ? summary.id : "",
+    name: typeof summary.name === "string" ? summary.name : "",
+    runnable_name: getRunnableName(summary),
+    description: typeof summary.description === "string" ? summary.description : null,
+    mode: typeof summary.mode === "string" ? summary.mode : null
+  };
+}
+function extractWorkflowInputVariables(dsl) {
+  if (!isPlainObject4(dsl)) {
+    return [];
+  }
+  const candidateNodeSets = [];
+  if (Array.isArray(dsl.nodes)) {
+    candidateNodeSets.push(dsl.nodes);
+  }
+  if (isPlainObject4(dsl.graph) && Array.isArray(dsl.graph.nodes)) {
+    candidateNodeSets.push(dsl.graph.nodes);
+  }
+  const variables = [];
+  for (const nodeSet of candidateNodeSets) {
+    for (const node of nodeSet) {
+      if (!isPlainObject4(node) || !isPlainObject4(node.data)) {
+        continue;
+      }
+      const nodeData = node.data;
+      if (nodeData.type !== "start" || !Array.isArray(nodeData.variables)) {
+        continue;
+      }
+      for (const variable of nodeData.variables) {
+        if (!isPlainObject4(variable) || typeof variable.variable !== "string") {
+          continue;
+        }
+        variables.push({
+          ...variable,
+          variable: variable.variable,
+          label: typeof variable.label === "string" ? variable.label : void 0,
+          required: typeof variable.required === "boolean" ? variable.required : void 0,
+          type: typeof variable.type === "string" ? variable.type : void 0
+        });
+      }
+    }
+  }
+  return variables;
+}
+function normalizeWorkflowDefinition(definition) {
+  return {
+    ...definition,
+    workflow_id: typeof definition.workflow_id === "string" ? definition.workflow_id : "",
+    app_id: typeof definition.app_id === "string" ? definition.app_id : "",
+    version: typeof definition.version === "string" ? definition.version : void 0,
+    name: typeof definition.name === "string" ? definition.name : "",
+    dsl: isPlainObject4(definition.dsl) ? definition.dsl : void 0,
+    context: typeof definition.context === "string" ? definition.context : void 0,
+    input_variables: extractWorkflowInputVariables(definition.dsl)
+  };
+}
+function invalidResponse(status, message) {
+  return {
+    data: null,
+    error: {
+      status,
+      message
+    },
+    status
+  };
+}
+function createWorkflowService(client) {
+  return {
+    async list(params = {}) {
+      const response = await client.http.request({
+        url: WORKFLOW_LIST_PATH,
+        method: "GET",
+        params: {
+          page: params.page ?? 1,
+          limit: params.limit ?? 20,
+          mode: params.mode ?? "workflow"
+        }
+      });
+      if (!response.data || !Array.isArray(response.data.data)) {
+        return invalidResponse(
+          response.status,
+          response.error?.message || "Invalid workflow list response structure"
+        );
+      }
+      return {
+        ...response,
+        data: {
+          ...response.data,
+          page: typeof response.data.page === "number" ? response.data.page : params.page ?? 1,
+          limit: typeof response.data.limit === "number" ? response.data.limit : params.limit ?? 20,
+          total: typeof response.data.total === "number" ? response.data.total : response.data.data.length,
+          has_more: typeof response.data.has_more === "boolean" ? response.data.has_more : false,
+          data: response.data.data.map(normalizeWorkflowSummary)
+        }
+      };
+    },
+    async get(workflowId) {
+      if (!workflowId) {
+        return invalidResponse(400, "workflowId is required");
+      }
+      const response = await client.http.request({
+        url: WORKFLOW_GET_PATH(workflowId),
+        method: "GET"
+      });
+      if (!response.data || !isPlainObject4(response.data)) {
+        return invalidResponse(
+          response.status,
+          response.error?.message || "Invalid workflow definition response structure"
+        );
+      }
+      return {
+        ...response,
+        data: normalizeWorkflowDefinition(response.data)
+      };
+    }
+  };
+}
 function loadOptionalJsonObjectInput3(input, label) {
   if (!input) {
     return {};
@@ -2366,6 +2513,128 @@ async function runWorkflow(client, options) {
     exitWithCommandError4(spinner, "Failed to run workflow", error);
   }
 }
+async function listWorkflows(client, options = {}) {
+  const spinner = createSpinner("Fetching workflows...", options.format);
+  try {
+    const workflowService = createWorkflowService(client);
+    const result = await workflowService.list({
+      page: options.page,
+      limit: options.limit,
+      mode: options.mode
+    });
+    if (result.error) {
+      spinner.fail("Failed to fetch workflows");
+      console.error(chalk4__default.default.red(result.error.message));
+      process.exit(1);
+    }
+    const payload = result.data;
+    const workflows = payload?.data || [];
+    spinner.succeed(`Found ${workflows.length} workflow${workflows.length === 1 ? "" : "s"}`);
+    renderOutput(payload, {
+      format: options.format,
+      tableRows: workflows.map((workflow) => ({
+        id: workflow.id,
+        runnableName: workflow.runnable_name,
+        platformName: workflow.name,
+        mode: workflow.mode,
+        description: workflow.description
+      })),
+      csvRows: workflows.map((workflow) => ({
+        id: workflow.id,
+        runnableName: workflow.runnable_name,
+        platformName: workflow.name,
+        mode: workflow.mode,
+        description: workflow.description
+      })),
+      ndjsonItems: workflows,
+      pretty: () => {
+        console.log(chalk4__default.default.blue("\nWorkflows\n"));
+        if (workflows.length === 0) {
+          console.log(chalk4__default.default.gray("No workflows found."));
+          return;
+        }
+        for (const workflow of workflows) {
+          console.log(`${chalk4__default.default.green("\u2022")} ${chalk4__default.default.bold(workflow.runnable_name || workflow.name)}`);
+          console.log(`  ${chalk4__default.default.gray("ID:")} ${workflow.id}`);
+          console.log(`  ${chalk4__default.default.gray("Platform Name:")} ${workflow.name}`);
+          console.log(`  ${chalk4__default.default.gray("Mode:")} ${workflow.mode || "workflow"}`);
+          if (workflow.description) {
+            console.log(`  ${chalk4__default.default.gray("Description:")} ${workflow.description}`);
+          }
+        }
+      }
+    });
+  } catch (error) {
+    exitWithCommandError4(spinner, "Failed to fetch workflows", error);
+  }
+}
+async function getWorkflow(client, options) {
+  const spinner = createSpinner(`Fetching workflow: ${options.id}...`, options.format);
+  try {
+    const workflowService = createWorkflowService(client);
+    const result = await workflowService.get(options.id);
+    if (result.error) {
+      spinner.fail("Failed to fetch workflow");
+      console.error(chalk4__default.default.red(result.error.message));
+      process.exit(1);
+    }
+    const workflow = result.data;
+    const inputVariables = workflow?.input_variables || [];
+    spinner.succeed("Workflow loaded");
+    renderOutput(workflow, {
+      format: options.format,
+      tableRows: workflow ? [
+        {
+          appId: workflow.app_id,
+          workflowId: workflow.workflow_id,
+          runnableName: workflow.name,
+          version: workflow.version || null,
+          inputVariables: inputVariables.map((item) => item.variable).join(", ")
+        }
+      ] : [],
+      csvRows: workflow ? [
+        {
+          appId: workflow.app_id,
+          workflowId: workflow.workflow_id,
+          runnableName: workflow.name,
+          version: workflow.version || null,
+          inputVariables: inputVariables.map((item) => item.variable).join(", ")
+        }
+      ] : [],
+      ndjsonItems: workflow ? [workflow] : [],
+      pretty: () => {
+        if (!workflow) {
+          console.log(chalk4__default.default.gray("No workflow found."));
+          return;
+        }
+        console.log(chalk4__default.default.blue(`
+Workflow: ${workflow.name}
+`));
+        console.log(`${chalk4__default.default.gray("App ID:")} ${workflow.app_id}`);
+        console.log(`${chalk4__default.default.gray("Workflow ID:")} ${workflow.workflow_id}`);
+        if (workflow.version) {
+          console.log(`${chalk4__default.default.gray("Version:")} ${workflow.version}`);
+        }
+        console.log(`
+${chalk4__default.default.gray("Input Variables:")}`);
+        if (inputVariables.length === 0) {
+          console.log(chalk4__default.default.gray("  none"));
+        } else {
+          for (const variable of inputVariables) {
+            const label = variable.label ? ` ${chalk4__default.default.gray(`(${variable.label})`)}` : "";
+            const type = variable.type ? ` ${chalk4__default.default.gray(`[${variable.type}]`)}` : "";
+            const required = variable.required ? chalk4__default.default.yellow(" required") : chalk4__default.default.gray(" optional");
+            console.log(`  - ${chalk4__default.default.bold(variable.variable)}${label}${type}${required}`);
+          }
+        }
+        console.log(`
+${chalk4__default.default.gray("Run With:")} amaster workflow run ${workflow.name} --app <app-code> --input '{...}'`);
+      }
+    });
+  } catch (error) {
+    exitWithCommandError4(spinner, "Failed to fetch workflow", error);
+  }
+}
 function exitWithCommandError5(spinner, failureMessage, error) {
   spinner.fail(failureMessage);
   const details = error instanceof Error ? error.message : String(error);
@@ -2774,11 +3043,12 @@ function createAmasterClient(appCode) {
   }
   const client$1 = client.createClient({
     baseURL: appConfig.baseURL,
-    ...token ? {
-      headers: {
+    headers: {
+      "x-app-code": appCode,
+      ...token ? {
         Authorization: `Bearer ${token}`
-      }
-    } : {},
+      } : {}
+    },
     onUnauthorized: () => {
       if (token) {
         console.error(chalk4__default.default.red("\n\u274C Session expired. Please login again."));
@@ -3331,7 +3601,25 @@ bpmCmd.command("start-form-deployed <key>").description("Get deployed start form
     format: options.format
   });
 });
-var workflowCmd = program.command("workflow").description("Run workflows");
+var workflowCmd = program.command("workflow").description("Inspect and run workflows");
+workflowCmd.command("list").description("List runnable workflows").option("--app <app-code>", "App code (uses default if not specified)").option("--page <n>", "Page number").option("--limit <n>", "Page size").addOption(
+  new commander.Option("--mode <mode>", "Workflow app mode").choices(["workflow", "chat", "completion", "agent-chat"])
+).addOption(createFormatOption()).action(async (options) => {
+  const appCode = resolveAppCode(options.app);
+  await listWorkflows(createAmasterClient(appCode), {
+    page: options.page ? parseInt(options.page, 10) : void 0,
+    limit: options.limit ? parseInt(options.limit, 10) : void 0,
+    mode: options.mode,
+    format: options.format
+  });
+});
+workflowCmd.command("get <id>").alias("inspect").description("Get workflow details and input variables by workflow app ID").option("--app <app-code>", "App code (uses default if not specified)").addOption(createFormatOption()).action(async (id, options) => {
+  const appCode = resolveAppCode(options.app);
+  await getWorkflow(createAmasterClient(appCode), {
+    id,
+    format: options.format
+  });
+});
 workflowCmd.command("run <name>").alias("execute").description("Run a workflow").option("--app <app-code>", "App code (uses default if not specified)").option("-i, --input <json>", "Workflow inputs object as JSON or @file").option("-r, --request <json>", "Full WorkflowRunRequest as JSON or @file").addOption(
   new commander.Option("--response-mode <mode>", "Workflow response mode").choices(["blocking", "streaming"])
 ).option("--user <user>", "Workflow user identifier").option("--files <json>", "Workflow files array as JSON or @file").option("--trace-id <traceId>", "Workflow trace ID").addOption(createFormatOption()).action(async (name, options) => {