codeer-cli 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

codeer_cli/cli.py

@@ -2,7 +2,7 @@
 
     codeer check
     codeer agent list|get|apply|diff|versions
-    codeer kb list|files|upload
+    codeer kb list|files|upload|faq-list|faq-get|faq-create|faq-update|faq-delete
     codeer eval list|evaluators|evaluator-create|evaluator-update|run|export|reconcile|cases-apply|rubrics|rubrics-apply
     codeer history list|get|conversations|negative-feedback
 """
@@ -18,7 +18,31 @@ from .commands import check
 
 
 def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog="codeer")
+    parser = argparse.ArgumentParser(
+        prog="codeer",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="Codeer CLI — self-describing agent lifecycle tools.",
+        epilog="""\
+Safe workflow for coding agents:
+  codeer check --json
+  codeer agent list
+  codeer agent get <agent-id> --full
+  codeer kb list
+  codeer eval list --agent <agent-id>
+  codeer eval evaluators
+  codeer agent diff --agent <agent-id> --from-version <n> --to-version <n>
+  codeer eval reconcile --agent <agent-id> --manifest .codeer/eval_cases.json
+
+Preview mutations before applying:
+  codeer agent apply --payload agent.json --dry-run
+  codeer eval cases-apply --agent <agent-id> --cases eval_cases.json --dry-run
+  codeer eval rubrics-apply --rubrics rubrics.json --dry-run
+  codeer kb upload --dir kb --name "Product KB" --dry-run
+  codeer kb faq-create --context-object-id <snapshot-object-id> --question "..." --dry-run
+
+Use --out <path> for large raw artifacts; stdout defaults to compact summaries.
+""",
+    )
     sub = parser.add_subparsers(dest="group")
 
     check.register(sub)
@@ -67,6 +91,16 @@ def main(argv: list[str] | None = None) -> int:
             client = CodeerClient.from_env()
         except AuthError as e:
             if args.group == "check":
+                if getattr(args, "json", False):
+                    print(json.dumps({
+                        "status": "fail",
+                        "auth": {
+                            "ok": False,
+                            "error": str(e),
+                        },
+                        "next_step": "Configure CODEER_API_KEY or a codeer profile",
+                    }, ensure_ascii=False, indent=2))
+                    return 1
                 print(f"FAIL  Auth: {e}", file=sys.stderr)
                 print("      Configure CODEER_API_KEY or a codeer profile", file=sys.stderr)
                 return 1

codeer_cli/commands/_util.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
+import json
 import sys
+from pathlib import Path
+from typing import Any
 
 
 def log(*args, **kwargs):
@@ -10,3 +13,54 @@ def log(*args, **kwargs):
 def truncate(text: str, n: int = 60) -> str:
     text = text.replace("\n", " ").strip()
     return text[:n] + "..." if len(text) > n else text
+
+
+NOISY_KEYS = {
+    "avatar",
+    "brand",
+    "creator",
+    "default_organization_id",
+    "default_scopes",
+    "default_workspace_id",
+    "is_owner",
+    "members",
+    "my_permissions",
+    "owner",
+    "profile",
+    "source_creator",
+    "user_role",
+    "workspace_organization_map",
+}
+
+
+def strip_noisy_fields(value: Any) -> Any:
+    """Remove server/account metadata that is not useful for agent lifecycle work."""
+    if isinstance(value, list):
+        return [strip_noisy_fields(item) for item in value]
+    if not isinstance(value, dict):
+        return value
+
+    out = {}
+    for key, item in value.items():
+        if key in NOISY_KEYS:
+            continue
+        if key == "workspace" and isinstance(item, dict):
+            out[key] = {
+                k: item.get(k)
+                for k in ("id", "name", "organization_id")
+                if item.get(k) is not None
+            }
+            continue
+        out[key] = strip_noisy_fields(item)
+    return out
+
+
+def print_json(value: Any) -> None:
+    print(json.dumps(value, ensure_ascii=False, indent=2, default=str))
+
+
+def write_json(path: str | None, value: Any) -> None:
+    if not path:
+        return
+    Path(path).write_text(json.dumps(value, ensure_ascii=False, indent=2, default=str) + "\n")
+    log(f"wrote full detail to {path}")

codeer_cli/commands/agent.py

@@ -2,33 +2,48 @@ from __future__ import annotations
 
 import difflib
 import json
-import sys
 from pathlib import Path
 from typing import Optional
 
 from .. import agents as agents_mod
 from ..client import CodeerClient
-from ._util import log
+from ._util import log, print_json, strip_noisy_fields, truncate, write_json
 
 
 def register(subparsers):
-    agent = subparsers.add_parser("agent", help="Agent CRUD, versioning, publishing")
+    agent = subparsers.add_parser("agent", help="Agent CRUD and versioning")
     sub = agent.add_subparsers(dest="action", required=True)
 
     # codeer agent list
-    p = sub.add_parser("list", help="List agents in workspace")
+    p = sub.add_parser(
+        "list",
+        help="List agents in workspace. Defaults to a lifecycle summary safe for Codex/Claude context.",
+    )
+    p.add_argument("--full", action="store_true",
+                   help="Print bounded detail instead of the default lifecycle summary.")
+    p.add_argument("--out", default=None,
+                   help="Write stripped full server detail to this file; stdout stays compact.")
     p.set_defaults(func=run_list)
 
     # codeer agent get <id>
-    p = sub.add_parser("get", help="Read agent details")
+    p = sub.add_parser(
+        "get",
+        help="Read one agent. Defaults to summary; use --full for prompt/tool detail or --out for an artifact.",
+    )
     p.add_argument("agent_id")
+    p.add_argument("--full", action="store_true",
+                   help="Print stripped full agent config, including system_prompt and tools.")
+    p.add_argument("--out", default=None,
+                   help="Write stripped full agent config to this file.")
     p.set_defaults(func=run_get)
 
     # codeer agent apply --payload agent.json
-    p = sub.add_parser("apply", help="Create or update agent from JSON payload")
+    p = sub.add_parser("apply", help="Create or update agent from JSON payload; run --dry-run first")
     p.add_argument("--payload", required=True, help="Path to agent payload JSON")
     p.add_argument("--agent-id", default=None, help="If set, PUT (update). Else POST (create).")
     p.add_argument("--note", default="", help="version_note for PUT")
+    p.add_argument("--dry-run", action="store_true",
+                   help="Validate payload and print intended mutation without writing server state.")
     p.add_argument("--out", default=None, help="Write result JSON to this file too")
     p.set_defaults(func=run_apply)
 
@@ -43,27 +58,104 @@ def register(subparsers):
     p.set_defaults(func=run_diff)
 
     # codeer agent versions --agent <id>
-    p = sub.add_parser("versions", help="List version history for an agent")
+    p = sub.add_parser(
+        "versions",
+        help="List version history. Defaults to version metadata only; use --out for full snapshots.",
+    )
     p.add_argument("--agent", required=True)
+    p.add_argument("--full", action="store_true",
+                   help="Add bounded prompt/tool size metadata; full snapshots still require --out.")
+    p.add_argument("--out", default=None,
+                   help="Write stripped full version snapshots to this file; stdout stays compact.")
     p.set_defaults(func=run_versions)
 
 
+def _tool_summary(tools: list[dict] | None) -> list[dict]:
+    out = []
+    for t in tools or []:
+        form = t.get("custom_form_schema") if isinstance(t.get("custom_form_schema"), dict) else {}
+        out.append({
+            "id": t.get("id"),
+            "type": t.get("type"),
+            "name": t.get("name"),
+            "knowledge_node_count": len(t.get("knowledge_node_ids") or []),
+            "form_title": form.get("title"),
+            "invocation_preview": truncate(t.get("invocation_instruction") or "", 160),
+        })
+    return out
+
+
+def _agent_summary(agent: dict, *, full: bool = False) -> dict:
+    tools = agent.get("unified_tools") or agent.get("tools") or []
+    row = {
+        "id": agent.get("id"),
+        "name": agent.get("name"),
+        "workspace": {
+            "id": agent.get("workspace_id") or (agent.get("workspace") or {}).get("id"),
+            "name": (agent.get("workspace") or {}).get("name"),
+        },
+        "publish_state": agent.get("publish_state"),
+        "version": agent.get("version"),
+        "latest_version_number": agent.get("latest_version_number"),
+        "published_version_number": agent.get("published_version_number"),
+        "publish_history_id": agent.get("publish_history_id"),
+        "llm_model": agent.get("llm_model"),
+        "agent_type": agent.get("agent_type"),
+        "updated_at": agent.get("updated_at"),
+        "tool_count": len(tools),
+        "system_prompt_chars": len(agent.get("system_prompt") or ""),
+    }
+    if full:
+        row["description"] = agent.get("description") or ""
+        row["use_search"] = agent.get("use_search")
+        row["suggested_questions"] = agent.get("suggested_questions") or []
+        row["tools"] = _tool_summary(tools)
+        row["system_prompt_preview"] = truncate(agent.get("system_prompt") or "", 1200)
+    return row
+
+
 
 def run_list(args, client) -> int:
     ws, org = client.resolve_scope()
     result = agents_mod.list_all(client, workspace_id=ws, organization_id=org)
-    print(json.dumps(result, ensure_ascii=False, indent=2, default=str))
+    write_json(args.out, strip_noisy_fields(result))
+    print_json([_agent_summary(a, full=args.full) for a in result])
     return 0
 
 
 def run_get(args, client) -> int:
     result = agents_mod.get(client, args.agent_id)
-    print(json.dumps(result, ensure_ascii=False, indent=2, default=str))
+    full_result = strip_noisy_fields(result)
+    write_json(args.out, full_result)
+    print_json(full_result if args.full else _agent_summary(result))
     return 0
 
 
 def run_apply(args, client) -> int:
     body = json.loads(Path(args.payload).read_text())
+    missing = [field for field in ("name", "system_prompt") if not body.get(field)]
+    if missing:
+        log(f"error: payload missing required field(s): {', '.join(missing)}")
+        return 2
+
+    if args.dry_run:
+        operation = "update" if args.agent_id else "create"
+        result = {
+            "dry_run": True,
+            "operation": operation,
+            "agent_id": args.agent_id,
+            "payload": str(Path(args.payload)),
+            "name": body.get("name"),
+            "system_prompt_chars": len(body.get("system_prompt") or ""),
+            "tool_count": len(body.get("unified_tools") or []),
+            "use_search": body.get("use_search", False),
+            "llm_model": body.get("llm_model"),
+            "version_note": args.note if args.agent_id else None,
+            "would_write_server_state": True,
+            "next_step": "Review this summary, then rerun without --dry-run after approval.",
+        }
+        print_json(result)
+        return 0
 
     if args.agent_id:
         body.pop("workspace_id", None)
@@ -118,7 +210,22 @@ def run_apply(args, client) -> int:
 
 def run_versions(args, client) -> int:
     versions = agents_mod.list_versions(client, args.agent)
-    print(json.dumps(versions, ensure_ascii=False, indent=2, default=str))
+    write_json(args.out, strip_noisy_fields(versions))
+    rows = []
+    for v in versions:
+        row = {
+            "id": v.get("id"),
+            "version_number": v.get("version_number"),
+            "status": v.get("status"),
+            "was_published": v.get("was_published"),
+            "version_note": v.get("version_note") or "",
+            "created_at": v.get("created_at"),
+        }
+        if args.full:
+            row["system_prompt_chars"] = len(v.get("system_prompt") or "")
+            row["tool_count"] = len(v.get("unified_tools") or v.get("tools") or [])
+        rows.append(row)
+    print_json(rows)
     return 0
 
 

codeer_cli/commands/check.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 import sys
 
 from ..client import AuthError, CodeerError
@@ -7,25 +8,46 @@ from ..client import AuthError, CodeerError
 
 def register(subparsers):
     p = subparsers.add_parser("check", help="Validate auth, workspace, and agent config")
+    p.add_argument("--json", action="store_true", help="Print machine-readable setup status")
     p.set_defaults(func=run)
 
 
 def run(args, client) -> int:
     errors = []
+    report = {
+        "status": "ok",
+        "auth": {"ok": False},
+        "workspace": {"ok": False},
+        "organization": {"ok": False},
+        "agent": {"ok": False, "configured": False, "optional": True},
+    }
 
     try:
         me = client.get_me()
     except AuthError:
+        if args.json:
+            report["status"] = "fail"
+            report["auth"]["error"] = "API key missing, invalid, expired, or revoked (401/403)"
+            report["next_step"] = "Create an admin workspace API key and export CODEER_API_KEY before running codeer"
+            print(json.dumps(report, ensure_ascii=False, indent=2))
+            return 1
         print("FAIL  Auth: API key missing, invalid, expired, or revoked (401/403)", file=sys.stderr)
         print("      Create an admin workspace API key and export CODEER_API_KEY before running codeer", file=sys.stderr)
         return 1
     except CodeerError as e:
+        if args.json:
+            report["status"] = "fail"
+            report["auth"]["error"] = str(e)
+            print(json.dumps(report, ensure_ascii=False, indent=2))
+            return 1
         print(f"FAIL  Auth: {e}", file=sys.stderr)
         return 1
 
     profile = me.get("profile", {})
     email = me.get("email") or "(unknown)"
-    print(f"  OK  Auth: logged in as {email}")
+    report["auth"] = {"ok": True, "email": email}
+    if not args.json:
+        print(f"  OK  Auth: logged in as {email}")
 
     try:
         ws_id, org_id = client.resolve_scope()
@@ -35,26 +57,45 @@ def run(args, client) -> int:
 
     if ws_id:
         ws_name = _workspace_name(profile, ws_id)
+        report["workspace"] = {"ok": True, "id": ws_id, "name": ws_name}
         if ws_name:
-            print(f"  OK  Workspace: {ws_name} ({ws_id})")
+            if not args.json:
+                print(f"  OK  Workspace: {ws_name} ({ws_id})")
         else:
-            print(f"  OK  Workspace: {ws_id}")
+            if not args.json:
+                print(f"  OK  Workspace: {ws_id}")
 
     if org_id:
-        print(f"  OK  Organization: {org_id}")
+        report["organization"] = {"ok": True, "id": org_id}
+        if not args.json:
+            print(f"  OK  Organization: {org_id}")
 
     agent_id = client.agent_id
     if agent_id:
+        report["agent"] = {"ok": False, "configured": True, "optional": True, "id": agent_id}
         try:
             agent = client.get(f"/external/agents/{agent_id}")
-            print(f"  OK  Agent: {agent.get('name', '(unnamed)')} ({agent_id})")
+            report["agent"].update({"ok": True, "name": agent.get("name", "(unnamed)")})
+            if not args.json:
+                print(f"  OK  Agent: {agent.get('name', '(unnamed)')} ({agent_id})")
         except CodeerError:
             errors.append(f"WARN  Agent: ID {agent_id} could not be read (may be in a different workspace)")
     else:
-        print("  --  Agent: CODEER_AGENT_ID not set (optional)")
-
-    for err in errors:
-        print(err, file=sys.stderr)
+        if not args.json:
+            print("  --  Agent: CODEER_AGENT_ID not set (optional)")
+
+    if errors:
+        report["messages"] = errors
+        if any(e.startswith("FAIL") for e in errors):
+            report["status"] = "fail"
+        elif report["status"] == "ok":
+            report["status"] = "warn"
+
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        for err in errors:
+            print(err, file=sys.stderr)
 
     return 1 if any(e.startswith("FAIL") for e in errors) else 0