@united-workforce/cli 0.4.0 → 0.6.0

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env -S node --disable-warning=ExperimentalWarning
 
-import type { CasRef, ThreadId, ThreadStatus } from "@united-workforce/protocol";
+import type { CasRef, OutputSchemaName, ThreadId, ThreadStatus } from "@united-workforce/protocol";
 import { Command } from "commander";
 import { cmdConfigGet, cmdConfigList, cmdConfigSet } from "./commands/config.js";
 import { cmdLogClean, cmdLogList, cmdLogShow } from "./commands/log.js";
@@ -16,6 +16,7 @@ import { cmdStepAsk, cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow } from "
 import {
   cmdThreadCancel,
   cmdThreadExec,
+  cmdThreadJoin,
   cmdThreadList,
   cmdThreadPoke,
   cmdThreadRead,
@@ -32,12 +33,61 @@ import {
   cmdWorkflowShow,
   cmdWorkflowValidate,
 } from "./commands/workflow.js";
-import { formatOutput, type OutputFormat } from "./format.js";
-import { resolveStorageRoot } from "./store.js";
+import {
+  formatOutput,
+  isOutputFormat,
+  type OutputFormat,
+  SUPPORTED_FORMATS,
+  writeEnvelope,
+} from "./format.js";
+import {
+  toStepDetailPayload,
+  toStepListPayload,
+  toThreadExecPayload,
+  toThreadListPayload,
+  toThreadStartPayload,
+  toThreadStatusPayload,
+  toValidateResultPayload,
+  toWorkflowAddPayload,
+  toWorkflowDetailPayload,
+  toWorkflowListPayload,
+} from "./output-mappers.js";
+import { createUwfStore, resolveStorageRoot } from "./store.js";
+
+function getFormat(): OutputFormat {
+  const raw = program.opts().format as string;
+  if (!isOutputFormat(raw)) {
+    process.stderr.write(
+      `Invalid --format: ${raw}. Must be one of: ${SUPPORTED_FORMATS.join(", ")}\n`,
+    );
+    process.exit(1);
+  }
+  return raw;
+}
+
+async function writeOutput(
+  payload: unknown,
+  schemaName: OutputSchemaName,
+  storageRoot: string,
+): Promise<void> {
+  const fmt = getFormat();
+  const uwf = await createUwfStore(storageRoot);
+  await writeEnvelope(payload, schemaName, {
+    format: fmt,
+    store: uwf.store,
+    schemas: uwf.schemas,
+  });
+}
 
-function writeOutput(data: unknown): void {
-  const fmt = program.opts().format as OutputFormat;
-  process.stdout.write(`${formatOutput(data, fmt)}\n`);
+/**
+ * Legacy raw output for commands without an output schema (log/config/setup).
+ * Always emits text/JSON/YAML based on the active --format. For `text`
+ * (the default) it renders via the per-command registry when available
+ * and falls back to JSON.
+ */
+function writeRawOutput(data: unknown, commandPath?: string): void {
+  const fmt = getFormat();
+  process.stdout.write(`${formatOutput(data, fmt, commandPath)}\n`);
 }
 
 function runAction(action: () => Promise<void>): void {
@@ -60,7 +110,11 @@ program
       "  workflow → thread → step → turn",
   )
   .version(pkg.default.version, "-V, --version");
-program.option("--format <fmt>", "Output format: json or yaml", "json");
+program.option(
+  "--format <fmt>",
+  "Output format: text (default), json, yaml, raw-json, raw-yaml",
+  "text",
+);
 
 const workflow = program
   .command("workflow")
@@ -74,7 +128,7 @@ workflow
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdWorkflowAdd(storageRoot, file);
-      writeOutput(result);
+      await writeOutput(toWorkflowAddPayload(result), "workflow-add", storageRoot);
     });
   });
 
@@ -83,9 +137,13 @@ workflow
   .description("Validate a workflow YAML without registering it (CI-friendly)")
   .argument("<file>", "Workflow YAML file")
   .action((file: string) => {
+    const storageRoot = resolveStorageRoot();
     runAction(async () => {
-      await cmdWorkflowValidate(file);
-      // silent on success — do not call writeOutput
+      const errors = await cmdWorkflowValidate(file);
+      await writeOutput(toValidateResultPayload(errors), "validate-result", storageRoot);
+      if (errors.length > 0) {
+        process.exit(1);
+      }
     });
   });
 
@@ -97,7 +155,7 @@ workflow
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdWorkflowShow(storageRoot, id, process.cwd());
-      writeOutput(result);
+      await writeOutput(toWorkflowDetailPayload(result), "workflow-detail", storageRoot);
     });
   });
 
@@ -108,7 +166,7 @@ workflow
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdWorkflowList(storageRoot, process.cwd());
-      writeOutput(result);
+      await writeOutput(toWorkflowListPayload(result), "workflow-list", storageRoot);
     });
   });
 
@@ -130,7 +188,7 @@ thread
         process.cwd(),
         opts.cwd ?? process.cwd(),
       );
-      writeOutput(result);
+      await writeOutput(toThreadStartPayload(result), "thread-start", storageRoot);
     });
   });
 
@@ -167,11 +225,7 @@ thread
           background,
           backgroundWorker,
         );
-        if (results.length === 1) {
-          writeOutput(results[0]);
-        } else {
-          writeOutput(results);
-        }
+        await writeOutput(toThreadExecPayload(results), "thread-exec", storageRoot);
       });
     },
   );
@@ -184,7 +238,7 @@ thread
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdThreadShow(storageRoot, threadId);
-      writeOutput(result);
+      await writeOutput(toThreadStatusPayload(result), "thread-status", storageRoot);
     });
   });
 
@@ -292,7 +346,7 @@ thread
           take,
           showAll,
         );
-        writeOutput(result);
+        await writeOutput(toThreadListPayload(result), "thread-list", storageRoot);
       });
     },
   );
@@ -314,7 +368,7 @@ thread
         supplement,
         agentOverride,
       );
-      writeOutput(result);
+      await writeOutput(toThreadStatusPayload(result), "thread-status", storageRoot);
     });
   });
 
@@ -334,7 +388,7 @@ thread
         opts.prompt,
         agentOverride,
       );
-      writeOutput(result);
+      await writeOutput(toThreadStatusPayload(result), "thread-status", storageRoot);
     });
   });
 
@@ -346,7 +400,7 @@ thread
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdThreadStop(storageRoot, threadId);
-      writeOutput(result);
+      writeRawOutput(result, "thread stop");
     });
   });
 
@@ -358,7 +412,25 @@ thread
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdThreadCancel(storageRoot, threadId);
-      writeOutput(result);
+      writeRawOutput(result, "thread cancel");
+    });
+  });
+
+thread
+  .command("join")
+  .description("Block until a running thread finishes, then return the final result")
+  .argument("<thread-id>", "Thread ULID")
+  .option("--timeout <seconds>", "Max seconds to wait before giving up")
+  .action((threadId: string, opts: { timeout: string | undefined }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const timeoutMs = opts.timeout !== undefined ? Number(opts.timeout) * 1000 : null;
+      if (timeoutMs !== null && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+        process.stderr.write("invalid --timeout: must be a positive number\n");
+        process.exit(1);
+      }
+      const results = await cmdThreadJoin(storageRoot, threadId, timeoutMs);
+      await writeOutput(toThreadExecPayload(results), "thread-exec", storageRoot);
     });
   });
 
@@ -401,7 +473,7 @@ step
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdStepList(storageRoot, threadId);
-      writeOutput(result);
+      await writeOutput(toStepListPayload(result), "step-list", storageRoot);
     });
   });
 
@@ -413,7 +485,11 @@ step
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const detail = await cmdStepShow(storageRoot, stepHash as CasRef);
-      writeOutput(detail);
+      await writeOutput(
+        toStepDetailPayload(stepHash as CasRef, detail),
+        "step-detail",
+        storageRoot,
+      );
     });
   });
 
@@ -475,7 +551,7 @@ step
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdStepFork(storageRoot, stepHash as CasRef);
-      writeOutput(result);
+      writeRawOutput(result);
     });
   });
 
@@ -618,7 +694,7 @@ program
   .command("setup")
   .description(
     "Configure the default agent. Run without --agent for interactive wizard.\n" +
-      "LLM provider/model configuration lives in <storage>/config.yaml under providers and models.",
+      "Each adapter owns its own LLM configuration — the engine config is LLM-free.",
   )
   .option("--agent <name>", "Default agent adapter (e.g. hermes → uwf-hermes)")
   .action((opts: { agent?: string }) => {
@@ -626,7 +702,7 @@ program
     runAction(async () => {
       if (opts.agent !== undefined && opts.agent !== "") {
         const result = await cmdSetup({ agent: opts.agent, storageRoot });
-        writeOutput(result);
+        writeRawOutput(result);
       } else {
         await cmdSetupInteractive(storageRoot);
       }
@@ -642,7 +718,7 @@ log
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdLogList(storageRoot);
-      writeOutput(result);
+      writeRawOutput(result, "log list");
     });
   });
 
@@ -665,7 +741,7 @@ log
           process: opts.process ?? null,
           date: opts.date ?? null,
         });
-        writeOutput(result);
+        writeRawOutput(result, "log show");
       });
     },
   );
@@ -678,7 +754,7 @@ log
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdLogClean(storageRoot, opts.before);
-      writeOutput(result);
+      writeRawOutput(result);
     });
   });
 
@@ -691,7 +767,7 @@ config
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdConfigList(storageRoot);
-      writeOutput(result);
+      writeRawOutput(result, "config list");
     });
   });
 
@@ -706,7 +782,7 @@ config
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdConfigGet(storageRoot, key);
-      writeOutput({ value: result });
+      writeRawOutput({ value: result }, "config get");
     });
   });
 
@@ -719,7 +795,7 @@ config
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdConfigSet(storageRoot, key, value);
-      writeOutput(result);
+      writeRawOutput(result, "config set");
     });
   });
 

package/src/commands/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { homedir } from "node:os";
+import { join, resolve as resolvePath } from "node:path";
 import { parse, stringify } from "yaml";
 
 /**
@@ -21,6 +22,12 @@ const VALID_CONFIG_KEYS: Record<
     // No knownFields — workflow/role names are user-defined
   },
   defaultAgent: { nested: false },
+  concurrency: {
+    nested: true,
+    knownFields: ["maxRunning"],
+    minDepth: 2,
+  },
+  workflowPaths: { nested: false },
 };
 
 /**
@@ -216,6 +223,31 @@ function parseArgsValue(value: string): unknown {
   throw new Error("Value for 'args' key must be a JSON array starting with '['");
 }
 
+/**
+ * Parse value for a top-level string array key (must be JSON array of strings).
+ */
+function parseStringArrayValue(value: string, keyName: string): unknown {
+  if (value.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(value);
+      if (!Array.isArray(parsed)) {
+        throw new Error("Value must be an array");
+      }
+      for (const item of parsed) {
+        if (typeof item !== "string") {
+          throw new Error(`All items must be strings, got ${typeof item}`);
+        }
+      }
+      return parsed;
+    } catch (error) {
+      throw new Error(
+        `Invalid JSON array for ${keyName}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  throw new Error(`Value for '${keyName}' must be a JSON array starting with '['`);
+}
+
 /**
  * Validate that we're not setting a property on a non-object
  */
@@ -260,10 +292,18 @@ export async function cmdConfigSet(
 
   const lastSegment = path[path.length - 1];
 
-  // Parse value if it's for an array key (args)
+  // Parse value if it's for an array key (args, workflowPaths)
   let parsedValue: unknown = value;
-  if (lastSegment === "args") {
+  if (path[0] === "workflowPaths") {
+    parsedValue = parseStringArrayValue(value, "workflowPaths");
+  } else if (lastSegment === "args") {
     parsedValue = parseArgsValue(value);
+  } else if (lastSegment === "maxRunning") {
+    const num = Number(value);
+    if (!Number.isInteger(num) || num < 1) {
+      throw new Error("Value for 'maxRunning' must be a positive integer");
+    }
+    parsedValue = num;
   }
 
   // Validate we're not setting a property on a non-object
@@ -274,3 +314,45 @@ export async function cmdConfigSet(
 
   return { key, value: parsedValue };
 }
+
+/**
+ * Expand leading `~/` in a path to the user's home directory.
+ */
+function expandTilde(p: string): string {
+  if (p.startsWith("~/") || p === "~") {
+    return join(homedir(), p.slice(1));
+  }
+  return p;
+}
+
+/**
+ * Load workflowPaths from config and resolve to absolute paths.
+ * Returns empty array if config doesn't exist or key is missing.
+ */
+export function loadWorkflowPaths(storageRoot: string): string[] {
+  const configPath = getConfigPath(storageRoot);
+  if (!existsSync(configPath)) {
+    return [];
+  }
+
+  let config: Record<string, unknown>;
+  try {
+    config = loadConfig(configPath);
+  } catch {
+    return [];
+  }
+
+  const raw = config.workflowPaths;
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+
+  const result: string[] = [];
+  for (const item of raw) {
+    if (typeof item === "string" && item.trim() !== "") {
+      const expanded = expandTilde(item.trim());
+      result.push(resolvePath(expanded));
+    }
+  }
+  return result;
+}

package/src/commands/prompt.ts

@@ -148,44 +148,36 @@ pipx install 'hermes-agent[acp]'
 pip install -e '.[acp]'
 \`\`\`
 
-### Step 2 — Configure provider and model
+### Step 2 — Configure default agent
 
-uwf needs an LLM provider to run agents. **Ask the user** for their provider, API key, and model, then run:
+Run the interactive wizard:
 
 \`\`\`bash
-uwf setup --provider <name> --api-key <key> --model <model> --agent <adapter-command>
+uwf setup
 \`\`\`
 
-**Note:** \`--agent\` takes the adapter **command name** (e.g. \`uwf-hermes\`), not the npm package name.
-
-**Preset providers** — when using a preset name, \`--base-url\` is auto-filled and can be omitted:
-
-| Provider | Name | Default base URL |
-|----------|------|-----------------|
-| OpenAI | \`openai\` | https://api.openai.com/v1 |
-| xAI | \`xai\` | https://api.x.ai/v1 |
-| OpenRouter | \`openrouter\` | https://openrouter.ai/api/v1 |
-| Venice | \`venice\` | https://api.venice.ai/api/v1 |
-| Dashscope | \`dashscope\` | https://dashscope.aliyuncs.com/compatible-mode/v1 |
-| DeepSeek | \`deepseek\` | https://api.deepseek.com/v1 |
-| SiliconFlow | \`siliconflow\` | https://api.siliconflow.cn/v1 |
-| VolcEngine | \`volcengine\` | https://ark.cn-beijing.volces.com/api/v3 |
-| Kimi (Moonshot) | \`kimi\` | https://api.moonshot.cn/v1 |
-| GLM (Zhipu AI) | \`glm\` | https://open.bigmodel.cn/api/paas/v4 |
-| StepFun | \`stepfun\` | https://api.stepfun.com/v1 |
-| MiniMax | \`minimax\` | https://api.minimax.io/v1 |
-| Ollama (local) | \`ollama\` | http://localhost:11434/v1 |
-
-For **non-preset providers**, you must specify \`--base-url\` manually.
-
-Example:
+Or configure non-interactively:
+
 \`\`\`bash
-uwf setup --provider openrouter --api-key sk-or-... --model anthropic/claude-sonnet-4 --agent uwf-hermes
+uwf setup --agent <adapter-command>
+\`\`\`
+
+**Note:** \`--agent\` takes the adapter **command name** (e.g. \`uwf-hermes\`, \`uwf-claude-code\`), not the npm package name.
+
+Config is saved to \`~/.uwf/config.yaml\`:
+
+\`\`\`yaml
+agents:
+  hermes:
+    command: uwf-hermes
+    args: []
+defaultAgent: hermes
+agentOverrides: {}
 \`\`\`
 
-If the user doesn't know what to choose, suggest \`openrouter\` with \`anthropic/claude-sonnet-4\` as a sensible default.
+**LLM configuration** is per-adapter — each adapter manages its own provider, model, and API key settings independently (typically via environment variables like \`CLAUDE_MODEL\`, \`ANTHROPIC_API_KEY\`, etc.). The engine config (\`~/.uwf/config.yaml\`) is LLM-free.
 
-Config is saved to \`~/.uwf/config.yaml\`. Verify with \`cat ~/.uwf/config.yaml\`.
+Verify with \`cat ~/.uwf/config.yaml\`.
 
 ### Step 3 — Install skills
 
@@ -339,5 +331,26 @@ uwf prompt workflow-authoring  # workflow YAML design guide
 uwf prompt adapter-developing  # building agent adapters
 uwf prompt bootstrap           # this guide
 \`\`\`
+
+## What's next — introduce uwf to the user
+
+After setup is complete, give the user a brief introduction to what uwf can do
+and invite them to try it. Cover these three things:
+
+1. **Run workflows** — execute pre-built workflows to automate multi-step tasks.
+   Setup auto-registers example workflows, ready to use immediately.
+2. **Create workflows** — design custom YAML workflows for their own recurring tasks
+   (code review, issue triage, release pipelines, etc.). Use \`uwf prompt workflow-authoring\`
+   for the authoring guide.
+3. **Debug & improve workflows** — iterate on workflow definitions, inspect thread state
+   with \`uwf thread show\`, replay failed steps with \`uwf thread poke\`, and refine
+   role procedures based on real execution results.
+
+**Discover & try built-in examples:**
+
+Run \`uwf workflow list\` to see which workflows are registered (setup auto-registers
+several built-in examples). Show the user what's available, then invite them to try
+one — for instance, suggest a fun debate topic like "AI 是否会抢了人类的工作？" and
+offer to kick it off for them.
 `;
 }

package/src/commands/setup.ts

@@ -1,9 +1,11 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { stdin as input, stdout as output } from "node:process";
 import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
 import { parse, stringify } from "yaml";
+import { cmdWorkflowAdd } from "./workflow.js";
 
 export type SetupArgs = {
   agent: string;
@@ -261,10 +263,56 @@ export function _checkAdapterAvailability(agentName: string): string[] {
   return warnings;
 }
 
+// ──────────────────────────────────────────────────────────────────────────────
+// Bundled example workflows
+// ──────────────────────────────────────────────────────────────────────────────
+
+/** Resolve the examples/ directory bundled with the CLI package. */
+function _findExamplesDir(): string | null {
+  // Walk up from this file (src/commands/ or dist/commands/) to the package root
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 5; i++) {
+    const candidate = join(dir, "examples");
+    if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+      return candidate;
+    }
+    dir = dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * Register bundled example workflows. Non-destructive — silently skips
+ * any that fail (e.g. already registered with same hash).
+ * Returns list of successfully registered workflow names.
+ */
+export async function _registerBundledExamples(storageRoot: string): Promise<string[]> {
+  const examplesDir = _findExamplesDir();
+  if (examplesDir === null) return [];
+
+  const registered: string[] = [];
+  const files = readdirSync(examplesDir)
+    .filter((f) => f.endsWith(".yaml"))
+    .sort();
+
+  for (const file of files) {
+    try {
+      const result = await cmdWorkflowAdd(storageRoot, join(examplesDir, file));
+      registered.push(result.name);
+      console.error(`  ✓ ${result.name}`);
+    } catch {
+      // Skip silently — workflow may already exist or be invalid
+    }
+  }
+
+  return registered;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+
 /**
  * Non-interactive setup. Engine config is LLM-free — only writes
- * agents + defaultAgent. LLM provider/model configuration lives in
- * config.yaml under `providers` and `models`.
+ * agents + defaultAgent. Each adapter owns its own LLM configuration.
  */
 export async function cmdSetup(args: SetupArgs): Promise<Record<string, unknown>> {
   const { storageRoot } = args;
@@ -287,16 +335,20 @@ export async function cmdSetup(args: SetupArgs): Promise<Record<string, unknown>
     console.error(`⚠ ${w}`);
   }
 
+  // Auto-register bundled example workflows
+  const registeredExamples = await _registerBundledExamples(storageRoot);
+
   return {
     configPath,
     defaultAgent: merged.defaultAgent,
     adapterWarnings,
+    registeredExamples,
   };
 }
 
 /**
- * Interactive setup — prompts the user only for the default agent. LLM
- * configuration lives in config.yaml under `providers` and `models`.
+ * Interactive setup — prompts the user only for the default agent.
+ * Each adapter owns its own LLM configuration.
  */
 export async function cmdSetupInteractive(storageRoot: string): Promise<Record<string, unknown>> {
   const rl = createInterface({ input, output });
@@ -313,8 +365,6 @@ export async function cmdSetupInteractive(storageRoot: string): Promise<Record<s
     console.log('  uwf thread start <name> -p "..."    Start a thread');
     console.log("  uwf thread exec <thread-id>         Execute next step");
     console.log("");
-    console.log("LLM config: edit ~/.uwf/config.yaml (providers + models sections).");
-    console.log("");
 
     return null as unknown as Record<string, unknown>;
   } finally {