buildify-cli 1.0.0__py3-none-any.whl

buildify_cli/cli.py

@@ -0,0 +1,1206 @@
+from __future__ import annotations
+
+import json
+import sys
+import time
+from dataclasses import replace
+from pathlib import Path
+from typing import Any, Optional
+
+import httpx
+import typer
+
+from buildify_cli import __version__
+from buildify_cli import exit_codes as ec
+from buildify_cli.client import OpenApiClient, interpret_r_body, operation_ok
+from buildify_cli.config import (
+    ENV_API_KEY,
+    ENV_BASE_URL,
+    ENV_JSON,
+    ENV_NO_PROMPT,
+    ENV_PROFILE,
+    API_KEY_SETUP_GUIDE,
+    MISSING_API_KEY_USER_MESSAGE,
+    RC_KEYS,
+    ResolvedConfig,
+    apply_key_test_metadata,
+    config_file_path,
+    env_flag,
+    list_stored_profiles,
+    load_file_config,
+    mask_api_key,
+    missing_api_key_payload,
+    normalize_api_key,
+    profile_public,
+    remove_profile,
+    resolve_config,
+    save_profile,
+    set_current_profile,
+    validate_profile_name,
+    write_config_file,
+    write_rc_key,
+)
+from buildify_cli.credential_form import (
+    default_credential_label,
+    default_credential_name,
+    form_fields,
+    prompt_payload,
+)
+from buildify_cli.output import human_err, is_tty, print_json
+from buildify_cli.publish_view import format_publish_report, is_publish_payload
+
+app = typer.Typer(
+    help="Buildify open API CLI: discover nodes, author workflows, validate, test run and deploy.",
+    epilog=(
+        "Default base URL: https://openapi.buildify.cn\n"
+        "Auth: Bearer <keyId>.<secret> — keys are issued in the console "
+        "(workspace settings → Open API keys), not via this CLI.\n"
+        "If no key is configured, an interactive TTY prompts and saves to ~/.buildifyrc (mode 600).\n\n"
+        "Subcommands:\n"
+        "  health           GET /openapi/v1/health (no key)\n"
+        "  key test         Validate the configured key\n"
+        "  bundle           Bundle / node discovery: list, nodes, node-properties, node-relations, doc, cred-types, cred-properties\n"
+        "  project          list, create, get, credentials, create-credential, workers\n"
+        "  workflow         list, create, get-draft, save-draft, validate, test-run, cancel-test,\n"
+        "                   deploy, published, deployment\n"
+        "  config           Manage the [openapi] section of ~/.buildifyrc\n"
+        "  version          Print CLI version\n"
+        "  help             Markdown reference on stdout (for AI/agents)\n\n"
+        f"Env: {ENV_BASE_URL}, {ENV_API_KEY}, {ENV_PROFILE}, {ENV_JSON}, {ENV_NO_PROMPT}\n"
+        "Exit: 0 ok | 1 generic | 2 auth/config | 3 local | 4 HTTP 4xx | 5 network"
+    ),
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    base_url: Optional[str] = typer.Option(
+        None, "--base-url", help=f"API base URL (default https://openapi.buildify.cn or {ENV_BASE_URL})."
+    ),
+    api_key: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        help=f"Bearer secret keyId.secret. Insecure in argv; prefer {ENV_API_KEY}, stdin, or ~/.buildifyrc.",
+    ),
+    json_out: bool = typer.Option(False, "--json", help="Print one JSON envelope on stdout; errors also JSON."),
+    profile: Optional[str] = typer.Option(
+        None,
+        "--profile",
+        help=f"Named key in ~/.buildifyrc. Overrides the current profile. Env: {ENV_PROFILE}.",
+    ),
+    quiet: bool = typer.Option(False, "--quiet", help="Less stderr noise."),
+) -> None:
+    ctx.ensure_object(dict)
+    if api_key:
+        human_err(
+            "warning: --api-key is visible in process lists and shell history; "
+            f"prefer `buildify config set-key api_key` or {ENV_API_KEY}"
+        )
+    ctx.obj["resolved"] = resolve_config(
+        cli_base_url=base_url,
+        cli_api_key=api_key,
+        cli_json=json_out,
+        cli_profile=profile,
+    )
+    ctx.obj["quiet"] = quiet
+
+
+def _cfg(ctx: typer.Context) -> ResolvedConfig:
+    return ctx.obj["resolved"]
+
+
+def _fail_local(ctx: typer.Context, msg: str, code: int = ec.LOCAL_VALIDATION, data: Any = None) -> typer.Exit:
+    """Report a client-side problem without ever reaching the network."""
+    if _cfg(ctx).json_output:
+        print_json(ok=False, code=0, msg=msg, http_status=0, data=data)
+    else:
+        human_err(msg)
+    return typer.Exit(code)
+
+
+def _can_prompt_for_key(ctx: typer.Context) -> bool:
+    if _cfg(ctx).json_output or env_flag(ENV_NO_PROMPT):
+        return False
+    return is_tty(sys.stdin) and is_tty(sys.stderr)
+
+
+def _prompt_api_key_secret() -> str:
+    """Hidden prompt; prints how-to-get + security notes on stderr. Never echoes the secret."""
+    human_err(API_KEY_SETUP_GUIDE)
+    human_err("")
+    raw = typer.prompt("Paste API key (input hidden)", hide_input=True, err=True)
+    return normalize_api_key(raw)
+
+
+def _save_api_key_locally(ctx: typer.Context, secret: str) -> str:
+    key = normalize_api_key(secret)
+    path = write_rc_key("api_key", key)
+    ctx.obj["resolved"] = replace(_cfg(ctx), api_key=key)
+    if not _cfg(ctx).json_output:
+        human_err(f"Saved api_key to {path} (mode 600, masked {mask_api_key(key)})")
+    return key
+
+
+def _require_api_key(ctx: typer.Context) -> str:
+    blocked = _cfg(ctx).auth_error
+    if blocked:
+        raise _fail_local(
+            ctx,
+            str(blocked.get("userMessage") or "api key profile is not selected"),
+            ec.AUTH_CONFIG,
+            data=blocked,
+        )
+    existing = _cfg(ctx).api_key
+    if existing:
+        return existing
+    if _can_prompt_for_key(ctx):
+        try:
+            return _save_api_key_locally(ctx, _prompt_api_key_secret())
+        except (ValueError, typer.Abort) as e:
+            msg = str(e) if isinstance(e, ValueError) else "api key not provided"
+            raise _fail_local(ctx, msg, ec.AUTH_CONFIG, data=missing_api_key_payload())
+    raise _fail_local(
+        ctx,
+        MISSING_API_KEY_USER_MESSAGE.strip(),
+        ec.AUTH_CONFIG,
+        data=missing_api_key_payload(),
+    )
+
+
+def _client(ctx: typer.Context, *, need_auth: bool = True) -> OpenApiClient:
+    cfg = _cfg(ctx)
+    key = _require_api_key(ctx) if need_auth else None
+    return OpenApiClient(cfg.base_url, key)
+
+
+def _emit(
+    ctx: typer.Context,
+    *,
+    http_status: int,
+    body: Any,
+    ok_override: Optional[bool] = None,
+    msg_override: Optional[str] = None,
+) -> int:
+    """Print result; return process exit code."""
+    cfg = _cfg(ctx)
+    code, smsg, data = interpret_r_body(body)
+    if http_status == 404:
+        data = _with_workspace_hint(ctx, data)
+    ok = ok_override if ok_override is not None else operation_ok(http_status, body)
+    msg = msg_override if msg_override is not None else (smsg or "")
+    if not msg and isinstance(body, dict):
+        msg = str(body.get("msg") or body.get("message") or "")
+    if not msg and not ok:
+        msg = str(body)[:500] if body is not None else "request failed"
+
+    if cfg.json_output:
+        print_json(
+            ok=ok,
+            code=code if code is not None else (200 if ok else http_status),
+            msg=msg,
+            http_status=http_status,
+            data=data,
+        )
+    elif ok:
+        payload = data if data is not None else body
+        if is_publish_payload(payload):
+            typer.echo(format_publish_report(payload))
+        else:
+            typer.echo(json.dumps(payload, ensure_ascii=False, indent=2) if payload is not None else "{}")
+    else:
+        human_err(f"[{http_status}] {msg}")
+
+    if ok:
+        return ec.OK
+    if http_status in (401, 403) or code in (401, 403):
+        return ec.AUTH_CONFIG
+    if 400 <= http_status < 600:
+        return ec.SERVER_CLIENT_ERROR
+    if code is not None and code != 200:
+        return ec.SERVER_CLIENT_ERROR
+    return ec.GENERIC
+
+
+def _with_workspace_hint(ctx: typer.Context, data: Any) -> Any:
+    """404 in the wrong workspace should tell the agent which key was used."""
+    cfg = _cfg(ctx)
+    hint = {
+        "tenantId": cfg.tenant_id,
+        "profile": cfg.profile,
+        "hint": (
+            "Resource was not found in the workspace bound to this key. "
+            "Run `buildify --json config profiles` before creating a project in another workspace."
+        ),
+    }
+    if isinstance(data, dict):
+        return {**data, **hint}
+    return {"body": data, **hint}
+
+
+def _emit_network_error(ctx: typer.Context, exc: BaseException) -> int:
+    msg = str(exc) or exc.__class__.__name__
+    if _cfg(ctx).json_output:
+        print_json(ok=False, code=0, msg=msg, http_status=0, data=None)
+    else:
+        human_err(msg)
+    return ec.NETWORK
+
+
+def _call(ctx: typer.Context, fn, *args, **kwargs) -> None:
+    """Run one client call and exit with the mapped code."""
+    try:
+        status, body = fn(*args, **kwargs)
+    except httpx.RequestError as e:
+        raise typer.Exit(_emit_network_error(ctx, e))
+    raise typer.Exit(_emit(ctx, http_status=status, body=body))
+
+
+def _fetch(ctx: typer.Context, fn, *args, **kwargs) -> Any:
+    """Run one client call and return R.data, or exit on failure."""
+    try:
+        status, body = fn(*args, **kwargs)
+    except httpx.RequestError as e:
+        raise typer.Exit(_emit_network_error(ctx, e))
+    if not operation_ok(status, body):
+        raise typer.Exit(_emit(ctx, http_status=status, body=body))
+    _, _, data = interpret_r_body(body)
+    return data
+
+
+def _read_json_arg(ctx: typer.Context, value: Optional[str], file: Optional[Path], *, what: str) -> Any:
+    """Accept inline JSON, a file path, or '-' for stdin."""
+    if value is not None and file is not None:
+        raise _fail_local(ctx, f"{what}: pass either the inline value or --file, not both")
+    raw: Optional[str] = None
+    if file is not None:
+        if str(file) == "-":
+            raw = sys.stdin.read()
+        else:
+            if not file.is_file():
+                raise _fail_local(ctx, f"{what}: not a file: {file}")
+            try:
+                raw = file.read_text(encoding="utf-8")
+            except OSError as e:
+                raise _fail_local(ctx, f"{what}: cannot read {file}: {e}")
+    elif value is not None:
+        raw = sys.stdin.read() if value == "-" else value
+    if raw is None:
+        raise _fail_local(ctx, f"{what} is required")
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise _fail_local(ctx, f"{what}: invalid JSON: {e}")
+
+
+@app.command("version")
+def cmd_version() -> None:
+    """Print CLI version (from package metadata when installed)."""
+    try:
+        from importlib.metadata import version
+
+        typer.echo(version("buildify-cli"))
+    except Exception:
+        typer.echo(__version__)
+
+
+@app.command("help")
+def cmd_help() -> None:
+    """Print Markdown usage reference on stdout (for AI agents and scripts)."""
+    typer.echo((Path(__file__).resolve().parent / "usage.md").read_text(encoding="utf-8"))
+
+
+@app.command("health")
+def cmd_health(ctx: typer.Context) -> None:
+    """GET /openapi/v1/health — no authentication."""
+    with _client(ctx, need_auth=False) as c:
+        _call(ctx, c.health)
+
+
+# --- key ---
+key_app = typer.Typer(help="API key operations.")
+app.add_typer(key_app, name="key")
+
+
+@key_app.command("test")
+def cmd_key_test(ctx: typer.Context) -> None:
+    """Validate the configured key and echo the workspace it belongs to.
+
+    Example: buildify --json key test
+    """
+    with _client(ctx) as c:
+        try:
+            status, body = c.key_test()
+        except httpx.RequestError as e:
+            raise typer.Exit(_emit_network_error(ctx, e))
+        if operation_ok(status, body):
+            _, _, data = interpret_r_body(body)
+            if isinstance(data, dict):
+                apply_key_test_metadata(_cfg(ctx).profile, data)
+        raise typer.Exit(_emit(ctx, http_status=status, body=body))
+
+
+# --- bundle ---
+bundle_app = typer.Typer(help="Bundle and node discovery (read-only).")
+app.add_typer(bundle_app, name="bundle")
+
+_OPT_BUNDLE = typer.Option(..., "--bundle", "-b", help="Bundle logical name (may contain /).")
+_OPT_BUNDLE_VERSION = typer.Option(
+    None, "--bundle-version", "-V", help="Bundle version; omit to use the latest installed version."
+)
+
+
+@bundle_app.command("list")
+def cmd_bundle_list(
+    ctx: typer.Context,
+    keyword: Optional[str] = typer.Option(None, "--keyword", "-k", help="Filter by name or label substring."),
+) -> None:
+    """Bundles usable by this workspace (owned + granted + system)."""
+    with _client(ctx) as c:
+        _call(ctx, c.bundle_list, keyword)
+
+
+@bundle_app.command("nodes")
+def cmd_bundle_nodes(
+    ctx: typer.Context,
+    bundle: str = _OPT_BUNDLE,
+    bundle_version: Optional[str] = _OPT_BUNDLE_VERSION,
+) -> None:
+    """Flattened node catalog: name, label, summary, icon, isTrigger."""
+    with _client(ctx) as c:
+        _call(ctx, c.bundle_nodes, bundle, bundle_version)
+
+
+@bundle_app.command("node-properties")
+def cmd_node_properties(
+    ctx: typer.Context,
+    bundle: str = _OPT_BUNDLE,
+    name: str = typer.Option(..., "--name", "-n", help="Node name (@FlowNodeDescription.name)."),
+    bundle_version: Optional[str] = _OPT_BUNDLE_VERSION,
+) -> None:
+    """Dynamic form schema of one node — also returns icon/label/summary for the canvas."""
+    with _client(ctx) as c:
+        _call(ctx, c.node_properties, bundle, bundle_version, name)
+
+
+@bundle_app.command("node-relations")
+def cmd_node_relations(
+    ctx: typer.Context,
+    bundle: str = _OPT_BUNDLE,
+    name: str = typer.Option(..., "--name", "-n", help="Node name (@FlowNodeDescription.name)."),
+    bundle_version: Optional[str] = _OPT_BUNDLE_VERSION,
+) -> None:
+    """Output relations of one node — copy the whole object onto `edges[].data.relations[]` (name/label/description, plus icon/_id for custom MCP relations)."""
+    with _client(ctx) as c:
+        _call(ctx, c.node_relations, bundle, bundle_version, name)
+
+
+@bundle_app.command("doc")
+def cmd_bundle_doc(
+    ctx: typer.Context,
+    bundle: str = _OPT_BUNDLE,
+    bundle_version: Optional[str] = _OPT_BUNDLE_VERSION,
+) -> None:
+    """Bundle README / usage document (Markdown)."""
+    with _client(ctx) as c:
+        _call(ctx, c.bundle_doc, bundle, bundle_version)
+
+
+@bundle_app.command("cred-types")
+def cmd_cred_types(
+    ctx: typer.Context,
+    bundle: str = _OPT_BUNDLE,
+    bundle_version: Optional[str] = _OPT_BUNDLE_VERSION,
+) -> None:
+    """Credential types declared by a bundle."""
+    with _client(ctx) as c:
+        _call(ctx, c.credentials_types, bundle, bundle_version)
+
+
+@bundle_app.command("cred-properties")
+def cmd_cred_properties(
+    ctx: typer.Context,
+    bundle: str = _OPT_BUNDLE,
+    type_: str = typer.Option(..., "--type", "-t", help="Credential type (PascalCase)."),
+    bundle_version: Optional[str] = _OPT_BUNDLE_VERSION,
+) -> None:
+    """Dynamic form schema of one credential type."""
+    with _client(ctx) as c:
+        _call(ctx, c.credentials_properties, bundle, bundle_version, type_)
+
+
+# --- project ---
+project_app = typer.Typer(help="Projects, credentials and workers.")
+app.add_typer(project_app, name="project")
+
+_OPT_PROJECT = typer.Option(..., "--project", "-p", help="Project public id (proj_...).")
+
+
+@project_app.command("list")
+def cmd_project_list(ctx: typer.Context) -> None:
+    """Projects in the workspace bound to the API key."""
+    with _client(ctx) as c:
+        _call(ctx, c.project_list)
+
+
+@project_app.command("create")
+def cmd_project_create(
+    ctx: typer.Context,
+    name: str = typer.Option(..., "--name", "-n", help="Project name."),
+    remark: Optional[str] = typer.Option(None, "--remark", help="Optional description."),
+) -> None:
+    """Create a project."""
+    with _client(ctx) as c:
+        _call(ctx, c.project_create, name, remark)
+
+
+@project_app.command("get")
+def cmd_project_get(ctx: typer.Context, project: str = _OPT_PROJECT) -> None:
+    """Project detail."""
+    with _client(ctx) as c:
+        _call(ctx, c.project_get, project)
+
+
+@project_app.command("credentials")
+def cmd_project_credentials(
+    ctx: typer.Context,
+    project: str = _OPT_PROJECT,
+    bundle: Optional[str] = typer.Option(None, "--bundle", "-b", help="Filter by bundle name."),
+) -> None:
+    """Credentials referenceable from a flow. Secrets are never returned.
+
+    Use `bundleName` / `type` / `name` from here to fill a node's `data.credentials`.
+    """
+    with _client(ctx) as c:
+        _call(ctx, c.project_credentials, project, bundle)
+
+
+@project_app.command("create-credential")
+def cmd_project_create_credential(
+    ctx: typer.Context,
+    project: str = _OPT_PROJECT,
+    bundle: str = _OPT_BUNDLE,
+    type_: str = typer.Option(..., "--type", "-t", help="Credential type (from `bundle cred-types`)."),
+    name: Optional[str] = typer.Option(None, "--name", "-n", help="Instance name referenced by flows. Confirm before create."),
+    label: Optional[str] = typer.Option(None, "--label", help="Display name. Confirm before create."),
+    description: Optional[str] = typer.Option(None, "--description", help="Optional remark."),
+    bundle_version: Optional[str] = _OPT_BUNDLE_VERSION,
+    data_inline: Optional[str] = typer.Option(
+        None,
+        "--data",
+        help="JSON object of form fields. Insecure in argv; prefer --file - / stdin.",
+    ),
+    file: Optional[Path] = typer.Option(
+        None,
+        "--file",
+        "-f",
+        help="JSON file of form fields, or '-' for stdin.",
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the TTY confirmation prompt."),
+) -> None:
+    """Create a project credential. Requires -p. Prompts for missing name/label/data.
+
+    Secrets are never printed. Agent: show returned defaults, wait for user confirm, then
+    pipe data JSON via stdin.
+    """
+    if data_inline:
+        human_err("warning: --data is visible in process lists and shell history; prefer --file -")
+    data: Optional[dict[str, Any]] = None
+    if data_inline is not None or file is not None:
+        parsed = _read_json_arg(ctx, data_inline, file, what="credential data")
+        if not isinstance(parsed, dict):
+            raise _fail_local(ctx, "credential data must be a JSON object")
+        data = parsed
+
+    with _client(ctx) as c:
+        project_row = _fetch(ctx, c.project_get, project)
+        project_name = str((project_row or {}).get("projectName") or project) if isinstance(project_row, dict) else project
+        types = _fetch(ctx, c.credentials_types, bundle, bundle_version) or []
+        type_row = next((row for row in types if isinstance(row, dict) and row.get("type") == type_), None)
+        if type_row is None and isinstance(types, list) and types:
+            raise _fail_local(
+                ctx,
+                f"凭证类型不存在: {type_}（请先 `bundle cred-types -b {bundle}`）",
+            )
+        type_label = str((type_row or {}).get("label") or type_)
+        resolved_version = bundle_version or (type_row or {}).get("bundleVersion")
+        props = _fetch(ctx, c.credentials_properties, bundle, resolved_version, type_) or {}
+        schema = props.get("schema") if isinstance(props, dict) else None
+        if not bundle_version and isinstance(props, dict) and props.get("bundleVersion"):
+            resolved_version = props.get("bundleVersion")
+        fields = form_fields(schema)
+        suggested_name = default_credential_name(bundle, type_)
+        suggested_label = default_credential_label(type_label, type_)
+
+        missing: list[str] = []
+        if not (name or "").strip():
+            missing.append("name")
+        if not (label or "").strip():
+            missing.append("label")
+        if data is None:
+            missing.append("data")
+
+        if missing and not _can_prompt_for_key(ctx):
+            payload = prompt_payload(
+                project_id=project,
+                project_name=project_name,
+                bundle_name=bundle,
+                bundle_version=str(resolved_version) if resolved_version else None,
+                type_name=type_,
+                type_label=type_label,
+                default_name=suggested_name,
+                default_label=suggested_label,
+                fields=fields,
+                missing=missing,
+            )
+            raise _fail_local(ctx, payload["userMessage"], ec.LOCAL_VALIDATION, data=payload)
+
+        chosen_name = (name or "").strip() or suggested_name
+        chosen_label = (label or "").strip() or suggested_label
+        if _can_prompt_for_key(ctx):
+            if not (name or "").strip():
+                chosen_name = str(typer.prompt("凭证 name（引用名）", default=suggested_name, err=True)).strip()
+            if not (label or "").strip():
+                chosen_label = str(typer.prompt("凭证 label（显示名）", default=suggested_label, err=True)).strip()
+            if data is None:
+                data = _prompt_credential_data(fields)
+            if not yes:
+                human_err("")
+                human_err("即将创建访问凭证，请确认：")
+                human_err(f"  项目：{project_name}")
+                human_err(f"  软件包：{bundle}")
+                human_err(f"  类型：{type_label}（{type_}）")
+                human_err(f"  name：{chosen_name}" + ("  （默认）" if chosen_name == suggested_name else ""))
+                human_err(f"  label：{chosen_label}" + ("  （默认）" if chosen_label == suggested_label else ""))
+                keys = ", ".join(field["name"] for field in fields) or "（无）"
+                human_err(f"  参数键：{keys}（值已隐藏）")
+                if not typer.confirm("确认创建？", default=False, err=True):
+                    raise _fail_local(ctx, "已取消创建", ec.LOCAL_VALIDATION)
+
+        if not chosen_name or not chosen_label:
+            raise _fail_local(ctx, "name 和 label 不能为空")
+        if data is None:
+            data = {}
+        _call(
+            ctx,
+            c.project_create_credential,
+            project,
+            bundle_name=bundle,
+            type_=type_,
+            name=chosen_name,
+            label=chosen_label,
+            data=data,
+            bundle_version=str(resolved_version) if resolved_version else None,
+            description=description,
+        )
+
+
+def _prompt_credential_data(fields: list[dict[str, Any]]) -> dict[str, Any]:
+    values: dict[str, Any] = {}
+    if not fields:
+        return values
+    human_err("请填写凭证参数（密钥类输入已隐藏）：")
+    for field in fields:
+        hint = f"{field['label']}（{field['name']}）"
+        if field.get("required"):
+            hint += " *"
+        default = field.get("default")
+        default_text = "" if default is None else str(default)
+        while True:
+            raw = typer.prompt(
+                hint,
+                default=default_text,
+                hide_input=bool(field.get("secret")),
+                show_default=not bool(field.get("secret")) and default_text != "",
+                err=True,
+            )
+            text = "" if raw is None else str(raw).strip()
+            if not text:
+                if field.get("required"):
+                    human_err("该项为必填")
+                    continue
+                break
+            values[field["name"]] = _coerce_credential_value(text, field)
+            break
+    return values
+
+
+def _coerce_credential_value(text: str, field: dict[str, Any]) -> Any:
+    ui = str(field.get("uiComponent") or "")
+    if ui == "InputNumber":
+        try:
+            return int(text) if text.lstrip("-").isdigit() else float(text)
+        except ValueError:
+            return text
+    if ui == "Switch":
+        lowered = text.lower()
+        if lowered in ("1", "true", "yes", "y"):
+            return True
+        if lowered in ("0", "false", "no", "n"):
+            return False
+    return text
+
+
+@project_app.command("workers")
+def cmd_project_workers(
+    ctx: typer.Context,
+    project: str = _OPT_PROJECT,
+    online_only: bool = typer.Option(False, "--online-only", help="Only workers currently online."),
+) -> None:
+    """Workers available to the project; a workerId is required to create or test run a flow."""
+    with _client(ctx) as c:
+        _call(ctx, c.project_workers, project, online_only)
+
+
+# --- flow ---
+flow_app = typer.Typer(help="Workflow authoring: create, draft, validate, test run, deploy.")
+app.add_typer(flow_app, name="workflow")
+
+_OPT_FLOW = typer.Option(..., "--flow", "-w", help="Workflow public id (wf_...).")
+_OPT_FLOW_JSON = typer.Option(None, "--flow-json", help="Inline canvas JSON, or '-' to read stdin.")
+_OPT_FLOW_FILE = typer.Option(None, "--file", "-f", help="Path to canvas JSON file, or '-' for stdin.")
+
+
+@flow_app.command("list")
+def cmd_flow_list(
+    ctx: typer.Context,
+    project: str = _OPT_PROJECT,
+    keyword: Optional[str] = typer.Option(None, "--keyword", "-k", help="Filter by workflow name."),
+) -> None:
+    """Workflows in a project."""
+    with _client(ctx) as c:
+        _call(ctx, c.flow_list, project, keyword)
+
+
+@flow_app.command("create")
+def cmd_flow_create(
+    ctx: typer.Context,
+    project: str = _OPT_PROJECT,
+    name: str = typer.Option(..., "--name", "-n", help="Workflow name."),
+    worker: list[str] = typer.Option(
+        ..., "--worker", help="Worker public id; repeat for multiple. See `buildify project workers`."
+    ),
+    remark: Optional[str] = typer.Option(None, "--remark", help="Optional description."),
+) -> None:
+    """Create a workflow with an empty draft."""
+    with _client(ctx) as c:
+        _call(ctx, c.flow_create, project, workflow_name=name, worker_ids=list(worker), remark=remark)
+
+
+@flow_app.command("get-draft")
+def cmd_flow_get_draft(ctx: typer.Context, project: str = _OPT_PROJECT, flow: str = _OPT_FLOW) -> None:
+    """Draft canvas JSON plus the optimistic-lock `version` needed to save it back."""
+    with _client(ctx) as c:
+        _call(ctx, c.flow_get_draft, project, flow)
+
+
+@flow_app.command("save-draft")
+def cmd_flow_save_draft(
+    ctx: typer.Context,
+    project: str = _OPT_PROJECT,
+    flow: str = _OPT_FLOW,
+    flow_json: Optional[str] = _OPT_FLOW_JSON,
+    file: Optional[Path] = _OPT_FLOW_FILE,
+    version: Optional[int] = typer.Option(
+        None, "--version", help="Optimistic-lock version; omit to read the current draft first."
+    ),
+) -> None:
+    """Save the canvas JSON as the draft.
+
+    Without --version the current draft is fetched to obtain it, so a concurrent edit
+    between read and write surfaces as a conflict instead of being silently overwritten.
+    """
+    payload = _read_json_arg(ctx, flow_json, file, what="flow json")
+    with _client(ctx) as c:
+        resolved_version = version
+        if resolved_version is None:
+            try:
+                status, body = c.flow_get_draft(project, flow)
+            except httpx.RequestError as e:
+                raise typer.Exit(_emit_network_error(ctx, e))
+            if not operation_ok(status, body):
+                raise typer.Exit(_emit(ctx, http_status=status, body=body))
+            _code, _msg, data = interpret_r_body(body)
+            resolved_version = (data or {}).get("version") if isinstance(data, dict) else None
+            if resolved_version is None:
+                raise _fail_local(ctx, "draft response has no `version`; pass --version explicitly", data=data)
+        _call(ctx, c.flow_save_draft, project, flow, workflow_json=payload, version=int(resolved_version))
+
+
+@flow_app.command("validate")
+def cmd_flow_validate(
+    ctx: typer.Context,
+    project: str = _OPT_PROJECT,
+    flow_json: Optional[str] = _OPT_FLOW_JSON,
+    file: Optional[Path] = _OPT_FLOW_FILE,
+) -> None:
+    """Check the canvas JSON against installed node schemas. No side effects.
+
+    Exits 4 when the flow has errors, so a script can loop until it passes.
+    """
+    payload = _read_json_arg(ctx, flow_json, file, what="flow json")
+    with _client(ctx) as c:
+        try:
+            status, body = c.flow_validate(project, payload)
+        except httpx.RequestError as e:
+            raise typer.Exit(_emit_network_error(ctx, e))
+    _code, _msg, data = interpret_r_body(body)
+    has_errors = isinstance(data, dict) and not data.get("valid", True)
+    code = _emit(ctx, http_status=status, body=body)
+    raise typer.Exit(ec.SERVER_CLIENT_ERROR if (code == ec.OK and has_errors) else code)
+
+
+@flow_app.command("test-run")
+def cmd_flow_test_run(
+    ctx: typer.Context,
+    project: str = _OPT_PROJECT,
+    worker: str = typer.Option(..., "--worker", help="Worker public id that runs the test."),
+    flow_json: Optional[str] = _OPT_FLOW_JSON,
+    file: Optional[Path] = _OPT_FLOW_FILE,
+    flow: Optional[str] = typer.Option(None, "--flow", "-w", help="Workflow public id, for logging context."),
+    start_node: Optional[str] = typer.Option(None, "--start-node", help="Node id to start from (single-node test)."),
+    inputs: Optional[str] = typer.Option(None, "--inputs", help="Inline JSON passed to the start node."),
+    timeout: Optional[int] = typer.Option(None, "--timeout", help="Seconds to wait for completion (server default 60)."),
+) -> None:
+    """Run the flow on a worker and wait for the aggregated result.
+
+    The call blocks until the worker reports completion or the timeout elapses;
+    node outputs are collected server-side from the execution event stream.
+    """
+    payload = _read_json_arg(ctx, flow_json, file, what="flow json")
+    parsed_inputs = json.loads(inputs) if inputs else None
+    with _client(ctx) as c:
+        _call(
+            ctx,
+            c.flow_test_run,
+            project,
+            workflow_json=payload,
+            worker_id=worker,
+            workflow_id=flow,
+            start_node_id=start_node,
+            inputs=parsed_inputs,
+            timeout_seconds=timeout,
+        )
+
+
+@flow_app.command("cancel-test")
+def cmd_flow_cancel_test(
+    ctx: typer.Context,
+    project: str = _OPT_PROJECT,
+    execution_id: str = typer.Option(..., "--execution-id", help="executionId from a test run."),
+    worker: str = typer.Option(..., "--worker", help="Worker the test was submitted to."),
+) -> None:
+    """Cancel a running test execution."""
+    with _client(ctx) as c:
+        _call(ctx, c.flow_cancel_test, project, execution_id, worker)
+
+
+_TERMINAL_DEPLOY = {"success", "success_with_warnings", "failed", "timeout", "canceled"}
+
+
+@flow_app.command("deploy")
+def cmd_flow_deploy(
+    ctx: typer.Context,
+    project: str = _OPT_PROJECT,
+    flow: str = _OPT_FLOW,
+    worker: list[str] = typer.Option(
+        ..., "--worker", help="Worker public id already bound to the flow; repeat for multiple."
+    ),
+    flow_json: Optional[str] = _OPT_FLOW_JSON,
+    file: Optional[Path] = _OPT_FLOW_FILE,
+    version: Optional[int] = typer.Option(
+        None, "--version", help="Optimistic-lock version; omit to read the current draft first."
+    ),
+    wait: bool = typer.Option(True, "--wait/--no-wait", help="Poll deployment until workers finish (default wait)."),
+    wait_seconds: int = typer.Option(60, "--wait-seconds", help="Max seconds to poll when --wait."),
+    remark: Optional[str] = typer.Option(None, "--remark", help="发布说明（写入该版本，最多 500 字；不改流程本身的描述）。"),
+    version_name: Optional[str] = typer.Option(
+        None, "--version-name", help="发布版本号，如 v1.0.0；省略则服务端生成 vyyyyMMdd-HHmmss。"
+    ),
+) -> None:
+    """Publish the saved draft to the given workers and return a human summary.
+
+    After save-draft, omit --file: the server publishes the current draft.
+    Set --version-name / --remark at publish time (version label and release note).
+    Pass --file only when you want to publish JSON that is not yet saved.
+    Uses the same workers the flow was created/test-run with. Does not pick servers.
+    """
+    payload: Optional[Any] = None
+    if flow_json is not None or file is not None:
+        payload = _read_json_arg(ctx, flow_json, file, what="flow json")
+    with _client(ctx) as c:
+        resolved_version = version
+        if payload is not None and resolved_version is None:
+            try:
+                status, body = c.flow_get_draft(project, flow)
+            except httpx.RequestError as e:
+                raise typer.Exit(_emit_network_error(ctx, e))
+            if not operation_ok(status, body):
+                raise typer.Exit(_emit(ctx, http_status=status, body=body))
+            _code, _msg, data = interpret_r_body(body)
+            draft = data if isinstance(data, dict) else {}
+            resolved_version = draft.get("version")
+            if resolved_version is None:
+                raise _fail_local(ctx, "draft response has no `version`; pass --version explicitly", data=data)
+        try:
+            status, body = c.flow_deploy(
+                project,
+                flow,
+                worker_ids=list(worker),
+                workflow_json=payload,
+                version=int(resolved_version) if resolved_version is not None else None,
+                remark=remark,
+                version_name=version_name,
+            )
+        except httpx.RequestError as e:
+            raise typer.Exit(_emit_network_error(ctx, e))
+        if not operation_ok(status, body) or not wait:
+            raise typer.Exit(_emit(ctx, http_status=status, body=body))
+        _code, _msg, data = interpret_r_body(body)
+        deployment_id = (data or {}).get("deploymentId") if isinstance(data, dict) else None
+        deploy_status = (data or {}).get("deployStatus") if isinstance(data, dict) else None
+        if not deployment_id:
+            raise typer.Exit(_emit(ctx, http_status=status, body=body))
+        deadline = time.monotonic() + max(1, wait_seconds)
+        last_status, last_body = status, body
+        while time.monotonic() < deadline:
+            try:
+                last_status, last_body = c.flow_deployment(project, flow, str(deployment_id), status_only=True)
+            except httpx.RequestError as e:
+                raise typer.Exit(_emit_network_error(ctx, e))
+            if not operation_ok(last_status, last_body):
+                raise typer.Exit(_emit(ctx, http_status=last_status, body=last_body))
+            _, _, snap = interpret_r_body(last_body)
+            deploy_status = (snap or {}).get("deployStatus") if isinstance(snap, dict) else None
+            if deploy_status in _TERMINAL_DEPLOY:
+                break
+            time.sleep(1)
+        try:
+            full_status, full_body = c.flow_deployment(project, flow, str(deployment_id))
+        except httpx.RequestError as e:
+            raise typer.Exit(_emit_network_error(ctx, e))
+        if operation_ok(full_status, full_body):
+            last_status, last_body = full_status, full_body
+            _, _, snap = interpret_r_body(last_body)
+            deploy_status = (snap or {}).get("deployStatus") if isinstance(snap, dict) else deploy_status
+        else:
+            last_status, last_body = full_status, full_body
+        code = _emit(ctx, http_status=last_status, body=last_body)
+        if deploy_status in {"failed", "timeout", "canceled"}:
+            raise typer.Exit(ec.SERVER_CLIENT_ERROR if code == ec.OK else code)
+        if deploy_status not in _TERMINAL_DEPLOY:
+            raise typer.Exit(ec.SERVER_CLIENT_ERROR if code == ec.OK else code)
+        raise typer.Exit(code)
+
+
+@flow_app.command("published")
+def cmd_flow_published(ctx: typer.Context, project: str = _OPT_PROJECT, flow: str = _OPT_FLOW) -> None:
+    """Current live version: project/workflow names, servers, nodes, credentials (no secrets)."""
+    with _client(ctx) as c:
+        _call(ctx, c.flow_published, project, flow)
+
+
+@flow_app.command("deployment")
+def cmd_flow_deployment(
+    ctx: typer.Context,
+    project: str = _OPT_PROJECT,
+    flow: str = _OPT_FLOW,
+    deployment: str = typer.Option(..., "--deployment", "-d", help="Deployment public id (deploy_...)."),
+) -> None:
+    """One deployment's overall status and per-server result."""
+    with _client(ctx) as c:
+        _call(ctx, c.flow_deployment, project, flow, deployment)
+
+
+# --- config ---
+config_app = typer.Typer(help="Write/read the openapi section of ~/.buildifyrc (overridden by env at runtime).")
+app.add_typer(config_app, name="config")
+
+
+def _read_secret_from_stdin() -> str:
+    return sys.stdin.read().strip()
+
+
+@config_app.command("init")
+def cmd_config_init(
+    ctx: typer.Context,
+    base_url: Optional[str] = typer.Option(None, "--base-url", help="Initial base_url (optional)."),
+    api_key: Optional[str] = typer.Option(
+        None, "--api-key", help="Initial api_key (optional; avoid in argv, prefer hidden prompt or stdin)."
+    ),
+) -> None:
+    """Create config with optional base_url / api_key; reads api_key from stdin when not a TTY."""
+    k = api_key
+    if k:
+        human_err("warning: --api-key is visible in process lists and shell history; prefer a hidden prompt or stdin")
+    if k is None:
+        if is_tty(sys.stdin) and not env_flag(ENV_NO_PROMPT):
+            if typer.confirm("Set API key now?", default=True, err=True):
+                try:
+                    k = _prompt_api_key_secret()
+                except (ValueError, typer.Abort) as e:
+                    raise _fail_local(ctx, str(e) if isinstance(e, ValueError) else "api key not provided", ec.AUTH_CONFIG)
+        else:
+            k = _read_secret_from_stdin() or None
+    try:
+        path = write_config_file(base_url=base_url, api_key=k)
+    except ValueError as e:
+        raise _fail_local(ctx, str(e))
+    masked = mask_api_key(k) if k else None
+    if _cfg(ctx).json_output:
+        print_json(
+            ok=True,
+            code=200,
+            msg="ok",
+            http_status=200,
+            data={"path": str(path), "api_key_masked": masked, "saved": bool(k)},
+        )
+    else:
+        typer.echo(f"Wrote {path} (mode 600)")
+        if masked:
+            typer.echo(f"api_key: {masked}")
+
+
+@config_app.command("set-key")
+def cmd_config_set_key(
+    ctx: typer.Context,
+    key: str = typer.Argument(..., help=f"One of: {', '.join(sorted(RC_KEYS))}."),
+    value: Optional[str] = typer.Argument(
+        None, help="For api_key: omit or '-' reads stdin (preferred); for base_url: required URL."
+    ),
+) -> None:
+    """Set one key in the openapi section (merge). Env vars still override at runtime."""
+    k = key.strip()
+    if k == "api_key":
+        if value is None or value == "-":
+            if is_tty(sys.stdin) and not env_flag(ENV_NO_PROMPT):
+                try:
+                    v = _prompt_api_key_secret()
+                except (ValueError, typer.Abort) as e:
+                    raise _fail_local(
+                        ctx,
+                        str(e) if isinstance(e, ValueError) else "api key not provided",
+                        ec.AUTH_CONFIG,
+                        data=missing_api_key_payload(),
+                    )
+            else:
+                v = _read_secret_from_stdin()
+        else:
+            human_err(
+                "warning: passing api_key as a command argument exposes it in process lists and shell history; "
+                "prefer stdin or the hidden prompt"
+            )
+            v = value
+        if not v:
+            raise _fail_local(ctx, "empty api key", ec.AUTH_CONFIG, data=missing_api_key_payload())
+    elif k == "base_url":
+        if value is None or value == "-":
+            raise _fail_local(ctx, "base_url requires a URL (e.g. https://openapi.buildify.cn)")
+        v = value
+    else:
+        raise _fail_local(ctx, f"unsupported key {k!r}; allowed: {', '.join(sorted(RC_KEYS))}")
+
+    try:
+        path = write_rc_key(k, v)
+    except ValueError as e:
+        raise _fail_local(ctx, str(e))
+
+    payload: dict[str, Any] = {"path": str(path), "key": k}
+    if k == "api_key":
+        payload["api_key_masked"] = mask_api_key(v)
+        payload["mode"] = "600"
+    if _cfg(ctx).json_output:
+        print_json(ok=True, code=200, msg="ok", http_status=200, data=payload)
+    else:
+        typer.echo(f"Updated {k} in {path} (mode 600)")
+        if k == "api_key":
+            typer.echo(f"api_key: {mask_api_key(v)}")
+
+
+def _read_api_key_value(ctx: typer.Context, value: Optional[str]) -> str:
+    if value is None or value == "-":
+        if is_tty(sys.stdin) and not env_flag(ENV_NO_PROMPT):
+            try:
+                return _prompt_api_key_secret()
+            except (ValueError, typer.Abort) as e:
+                raise _fail_local(
+                    ctx,
+                    str(e) if isinstance(e, ValueError) else "api key not provided",
+                    ec.AUTH_CONFIG,
+                    data=missing_api_key_payload(),
+                )
+        v = _read_secret_from_stdin()
+    else:
+        human_err(
+            "warning: passing api_key as a command argument exposes it in process lists and shell history; "
+            "prefer stdin or the hidden prompt"
+        )
+        v = value
+    if not v:
+        raise _fail_local(ctx, "empty api key", ec.AUTH_CONFIG, data=missing_api_key_payload())
+    return v
+
+
+@config_app.command("add-profile")
+def cmd_config_add_profile(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Profile name (letters, digits, ., _, -). Does not change the default."),
+    value: Optional[str] = typer.Argument(
+        None, help="Omit or '-' reads the key from stdin (preferred)."
+    ),
+) -> None:
+    """Save a workspace key under a name. Does not change the default profile."""
+    try:
+        profile_name = validate_profile_name(name)
+    except ValueError as e:
+        raise _fail_local(ctx, str(e))
+    secret = _read_api_key_value(ctx, value)
+    try:
+        path = save_profile(profile_name, secret)
+        key = normalize_api_key(secret)
+    except ValueError as e:
+        raise _fail_local(ctx, str(e), ec.AUTH_CONFIG, data=missing_api_key_payload())
+
+    metadata_saved = False
+    try:
+        with OpenApiClient(_cfg(ctx).base_url, key) as client:
+            status, body = client.key_test()
+        if operation_ok(status, body):
+            _, _, data = interpret_r_body(body)
+            if isinstance(data, dict):
+                metadata_saved = apply_key_test_metadata(profile_name, data)
+    except httpx.RequestError:
+        metadata_saved = False
+
+    payload = {
+        "path": str(path),
+        "profile": profile_name,
+        "api_key_masked": mask_api_key(key),
+        "mode": "600",
+        "metadataSaved": metadata_saved,
+    }
+    if _cfg(ctx).json_output:
+        print_json(ok=True, code=200, msg="ok", http_status=200, data=payload)
+    else:
+        typer.echo(f"Saved profile {profile_name} to {path} (mode 600, masked {mask_api_key(key)})")
+        if not metadata_saved:
+            human_err("key test did not cache workspace metadata; run `buildify --profile "
+                      f"{profile_name} key test` when the API is reachable")
+
+
+@config_app.command("use")
+def cmd_config_use(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Profile name to make the default."),
+) -> None:
+    """Set the default profile. Agents should pass --profile instead of calling this."""
+    try:
+        path = set_current_profile(name)
+    except ValueError as e:
+        raise _fail_local(ctx, str(e), ec.AUTH_CONFIG)
+    if _cfg(ctx).json_output:
+        print_json(
+            ok=True,
+            code=200,
+            msg="ok",
+            http_status=200,
+            data={"path": str(path), "current": name.strip()},
+        )
+    else:
+        typer.echo(f"current profile: {name.strip()} ({path})")
+
+
+@config_app.command("profiles")
+def cmd_config_profiles(ctx: typer.Context) -> None:
+    """List saved profiles. JSON output has no api_key."""
+    section = load_file_config()
+    current = section.get("current")
+    current_name = str(current).strip() if current else None
+    rows = [profile_public(p, current_name) for p in list_stored_profiles(section)]
+    if _cfg(ctx).json_output:
+        print_json(
+            ok=True,
+            code=200,
+            msg="ok",
+            http_status=200,
+            data={"current": current_name, "profiles": rows},
+        )
+    else:
+        if not rows:
+            typer.echo("(no profiles)")
+            return
+        for row in rows:
+            mark = "*" if row["current"] else " "
+            tenant = row["tenantId"] or "-"
+            key_name = row["keyName"] or "-"
+            prefix = row["keyPrefix"] or "-"
+            typer.echo(f"{mark} {row['name']}\ttenant={tenant}\tkey={key_name}\tprefix={prefix}")
+
+
+@config_app.command("remove-profile")
+def cmd_config_remove_profile(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Profile name to delete."),
+) -> None:
+    """Delete one saved profile. If it was current, the default is cleared."""
+    try:
+        path = remove_profile(name)
+    except ValueError as e:
+        raise _fail_local(ctx, str(e), ec.AUTH_CONFIG)
+    if _cfg(ctx).json_output:
+        print_json(
+            ok=True,
+            code=200,
+            msg="ok",
+            http_status=200,
+            data={"path": str(path), "removed": name.strip()},
+        )
+    else:
+        typer.echo(f"removed profile {name.strip()} from {path}")
+
+
+@config_app.command("show")
+def cmd_config_show(ctx: typer.Context) -> None:
+    """Show base_url and masked api_key stored in ~/.buildifyrc (not merged with env)."""
+    path = config_file_path()
+    data = load_file_config()
+    base = data.get("base_url") or "(not set)"
+    current = data.get("current")
+    current_name = str(current).strip() if current else None
+    profiles = list_stored_profiles(data)
+    chosen = next((p for p in profiles if p.name == current_name), None)
+    if chosen is None and len(profiles) == 1:
+        chosen = profiles[0]
+    masked = mask_api_key(chosen.api_key) if chosen else "(not set)"
+    mode = oct(path.stat().st_mode & 0o777) if path.is_file() else None
+    public_rows = [profile_public(p, current_name) for p in profiles]
+    if _cfg(ctx).json_output:
+        print_json(
+            ok=True,
+            code=200,
+            msg="ok",
+            http_status=200,
+            data={
+                "path": str(path),
+                "section": "openapi",
+                "base_url": base,
+                "current": current_name,
+                "profile": chosen.name if chosen else None,
+                "api_key_masked": masked,
+                "profiles": public_rows,
+                "mode": mode,
+            },
+        )
+    else:
+        typer.echo(f"path: {path} [openapi]")
+        typer.echo(f"base_url: {base}")
+        typer.echo(f"current: {current_name or '(not set)'}")
+        typer.echo(f"api_key: {masked}")
+        if mode:
+            typer.echo(f"mode: {mode}")
+        typer.echo("(runtime: BUILDIFY_OPENAPI_* env overrides file)")
+
+
+if __name__ == "__main__":
+    app()