operx-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{operx_cli-0.5.0 → operx_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: operx-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: La línea de comandos de OperX: tu empresa desde la terminal, con tu token de API.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -196,7 +196,9 @@ llevas el SG-SST o lo ambiental de tus clientes, `operx sst empresas` y
 ### Antes de escribir
 
 Todo lo que crea o cambia algo pregunta antes. En un script o una tarea
-programada no hay a quién preguntar: agrega `--si`. Cada escritura queda en
+programada no hay a quién preguntar: agrega `--si`. Con `--json`, lo que
+escribe responde el registro creado o cambiado (con su `id`) en vez de una
+frase. Cada escritura queda en
 el historial del token (Acceso por API › el token › Actividad) marcada como
 hecha desde la CLI.
 
@@ -211,13 +213,17 @@ Usuarios y acceso.
 
 ### Cualquier otra llamada
 
-Lo que no tiene comando propio se hace con `operx api`. `operx api rutas`
-lista todas las direcciones que tu token puede llamar (`operx api rutas
-compresor` deja las que lo mencionan); también están en Acceso por API ›
-Documentación:
+Lo que no tiene comando propio se hace con `operx api`: todo lo que tu
+token puede hacer, más de 400 llamadas. `operx api rutas` las lista
+(`operx api rutas sst inspections` deja las que tienen esas palabras), y
+`operx api campos RUTA` dice qué lleva una: sus filtros, cada campo con su
+tipo, si es obligatorio y los valores permitidos. También están en Acceso
+por API › Documentación:
 
 ```sh
-operx api rutas schedules
+operx api rutas repuestos
+operx api campos inventory/work-orders/1234/parts/ --metodo POST
+operx api POST inventory/work-orders/1234/parts/ -d '{"action": "usar", "item": 3, "quantity": "2", "location": 2}'
 operx api GET pm/schedules/ -q search=compresor
 operx api POST contacts/ -d @contacto.json
 operx api GET work-orders/export/ -o ordenes.csv

{operx_cli-0.5.0 → operx_cli-0.6.0}/README.md

@@ -182,7 +182,9 @@ llevas el SG-SST o lo ambiental de tus clientes, `operx sst empresas` y
 ### Antes de escribir
 
 Todo lo que crea o cambia algo pregunta antes. En un script o una tarea
-programada no hay a quién preguntar: agrega `--si`. Cada escritura queda en
+programada no hay a quién preguntar: agrega `--si`. Con `--json`, lo que
+escribe responde el registro creado o cambiado (con su `id`) en vez de una
+frase. Cada escritura queda en
 el historial del token (Acceso por API › el token › Actividad) marcada como
 hecha desde la CLI.
 
@@ -197,13 +199,17 @@ Usuarios y acceso.
 
 ### Cualquier otra llamada
 
-Lo que no tiene comando propio se hace con `operx api`. `operx api rutas`
-lista todas las direcciones que tu token puede llamar (`operx api rutas
-compresor` deja las que lo mencionan); también están en Acceso por API ›
-Documentación:
+Lo que no tiene comando propio se hace con `operx api`: todo lo que tu
+token puede hacer, más de 400 llamadas. `operx api rutas` las lista
+(`operx api rutas sst inspections` deja las que tienen esas palabras), y
+`operx api campos RUTA` dice qué lleva una: sus filtros, cada campo con su
+tipo, si es obligatorio y los valores permitidos. También están en Acceso
+por API › Documentación:
 
 ```sh
-operx api rutas schedules
+operx api rutas repuestos
+operx api campos inventory/work-orders/1234/parts/ --metodo POST
+operx api POST inventory/work-orders/1234/parts/ -d '{"action": "usar", "item": 3, "quantity": "2", "location": 2}'
 operx api GET pm/schedules/ -q search=compresor
 operx api POST contacts/ -d @contacto.json
 operx api GET work-orders/export/ -o ordenes.csv

{operx_cli-0.5.0 → operx_cli-0.6.0}/operx_cli/AGENTES.md

@@ -9,8 +9,9 @@ llamada queda en el historial del token, marcada como hecha desde la CLI.
 
 1. Escribe siempre el comando completo (`operx ordenes listar …`). No abras el
    modo interactivo: `operx` solo, fuera de una terminal, solo muestra la ayuda.
-2. Lee con `--json`: es lo que responde la API, completo. Las tablas son para
-   personas.
+2. Usa `--json` siempre: al leer es lo que responde la API, completo; al
+   escribir es el registro creado o cambiado, con su `id`. Las tablas y las
+   frases son para personas.
 3. Antes de crear o cambiar algo, dile a la persona qué vas a hacer y espera
    su sí. Con su sí, agrega `--si`: sin él, toda escritura falla fuera de una
    terminal.
@@ -20,7 +21,9 @@ llamada queda en el historial del token, marcada como hecha desde la CLI.
    consulta primero si quedó hecha.
 6. Si un nombre coincide con varios registros, `operx` lo dice con sus ids:
    usa el id, no adivines.
-7. Usa un comando propio cuando exista; `operx api` es para lo demás.
+7. Usa un comando propio cuando exista: acepta nombres y fechas como los
+   escribe la persona. Para todo lo demás está `operx api` (abajo): con él
+   puedes hacer todo lo que el token permite.
 8. `operx update` y `operx completar` cambian el computador de la persona, no
    los datos de su empresa: son para ella, no los ejecutes.
 
@@ -54,6 +57,8 @@ llamada queda en el historial del token, marcada como hecha desde la CLI.
 
 ## Escribir
 
+- Todos los comandos que escriben aceptan `--json`: la salida es solo la
+  respuesta de la API (el registro, con su `id`). Úsalo para encadenar pasos.
 - Escriben: `ordenes crear`, `ordenes editar`, `ordenes estado`,
   `ordenes asignar`, `ordenes comentar`, `ordenes adjuntar`,
   `preventivos crear`, `preventivos nota`, `equipos crear`, `equipos editar`,
@@ -110,13 +115,46 @@ Lo que responde la API:
 - **429**: demasiadas llamadas (120 por minuto por token, 600 por empresa).
   `operx` espera y reintenta solo, hasta 3 veces.
 
-## Cualquier otra llamada: `operx api`
-
-`operx api MÉTODO RUTA` hace cualquier llamada que el token pueda hacer y
-responde el JSON de la API. `operx api rutas --json` lista todas las rutas
-que el token puede llamar, con lo que hace cada una; `operx api rutas TEXTO`
-deja solo las que lo mencionan. Escríbelas como salen ahí: sin `/api/v1/` y
-sin barra inicial.
+## Todo lo demás: `operx api`
+
+El token puede hacer más de 400 llamadas; los comandos propios cubren las
+del día a día. Todas las demás se hacen con `operx api MÉTODO RUTA`, en
+cinco pasos:
+
+1. **Busca la ruta.** `operx api rutas TEXTO --json` deja las que tienen
+   cada palabra del texto en la ruta, en su `producto` (SG-SST, Inventario…)
+   o en lo que hace. Las rutas están en inglés: busca también así
+   (`operx api rutas sst inspections`, `operx api rutas repuestos`).
+2. **Lee lo que lleva.** `operx api campos RUTA --json` (con `--metodo POST`
+   para uno solo) da, por método:
+   - `en_la_ruta`: los valores de la dirección, como `{pk}`.
+   - `filtros`: lo que va en `-q nombre=valor`.
+   - `datos`: cada campo del cuerpo, con su `tipo`, su `formato`, si es
+     `obligatorio`, y en `valores` los permitidos con su etiqueta en español
+     (para entender lo que dice la persona). `lines[].item` es un campo de
+     cada elemento de la lista `lines`.
+   - `envio`: `json` (todo en `-d`) o `archivos` (el archivo con
+     `-a campo=ruta`, lo demás en `-d`).
+   - `responde`: los campos de la respuesta.
+3. **Busca los ids.** La API toma ids, no nombres: búscalos con un comando
+   (`operx equipos listar --buscar bomba --json`) o con
+   `operx api GET RUTA -q search=TEXTO`.
+4. **Escribe**, después del sí de la persona: `-d '{"campo": valor}'` y `--si`.
+5. **Lee la respuesta**: es el registro creado o cambiado.
+
+En `-d` los datos van como los toma la API, no como en los comandos propios:
+
+- Decimales como texto con punto: `"2.5"`, nunca `2,5`.
+- Fechas `"2026-10-30"`; fecha y hora con su zona:
+  `"2026-10-30T08:00:00-05:00"`.
+- Ids, no nombres: `"item": 3`, no `"item": "FIL-010"`.
+- Los valores de una lista, en inglés, como salen en `valores`:
+  `"priority": "high"`.
+
+Si la API responde 400, el mensaje dice qué campo falló y por qué; corrige
+eso, no lo demás.
+
+Más opciones de `operx api`:
 
 - `-q nombre=valor`: un filtro. Se repite.
 - `-d '{"campo": "valor"}'` o `-d @archivo.json`: el cuerpo de la llamada.
@@ -125,9 +163,9 @@ sin barra inicial.
 - `-o archivo`: guarda una respuesta que es un archivo (CSV, PDF).
 
 ```sh
-operx api rutas schedules --json
-operx api GET pm/schedules/ -q search=compresor
-operx api POST contacts/ -d @contacto.json --si
+operx api rutas repuestos --json
+operx api campos inventory/work-orders/1234/parts/ --metodo POST --json
+operx api POST inventory/work-orders/1234/parts/ -d '{"action": "usar", "item": 3, "quantity": "2", "location": 2}' --si
 operx api GET work-orders/export/ -o ordenes.csv
 ```
 
@@ -155,6 +193,15 @@ operx inventario entrada --articulo CON-0001 --lugar "Bodega central" --cantidad
 # Un equipo que entró a mantenimiento
 operx equipos editar BOM-04 --estado en-mantenimiento --si
 
+# Un repuesto usado en una orden (no tiene comando propio): ruta, campos, ids, escribir
+operx api rutas repuestos --json
+operx api campos inventory/work-orders/1234/parts/ --metodo POST --json
+operx inventario existencias --buscar filtro --json
+operx api POST inventory/work-orders/1234/parts/ -d '{"action": "usar", "item": 3, "quantity": "2", "location": 2}' --si
+
+# Crear y seguir con el id que responde
+operx ordenes crear --titulo "Cambio de rodamiento" --equipo BOM-04 --si --json
+
 # Los equipos en un CSV para Excel
 operx equipos listar --todas --csv > equipos.csv
 

{operx_cli-0.5.0 → operx_cli-0.6.0}/operx_cli/__init__.py

@@ -2,4 +2,4 @@
 API (backend/users/api_allowlist.py) from a terminal, with a personal API
 token."""
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"

operx_cli-0.6.0/operx_cli/api_fields.py

@@ -0,0 +1,232 @@
+"""What a route takes, read from the OpenAPI schema the API serves a token
+(auth/api-tokens/schema/, drf-spectacular): the values in its address, its
+filters, the fields of its body and what it answers. `operx api campos`
+prints it, so an AI agent can call any route with `operx api` without
+guessing; no network here, so the MCP server can use it as it is.
+
+The schema's shapes this follows: a field's type behind a $ref; an allOf
+of one $ref (a nested record); a oneOf of an enum with BlankEnum and
+NullEnum (a choice that may be "" or null); each enum's labels in its
+description, one "* `value` - Label" a line.
+"""
+
+import re
+
+METHODS = ("get", "post", "put", "patch", "delete")
+# A field inside a list inside a list… is shown this many levels deep.
+MAX_DEPTH = 3
+LABEL_LINE = re.compile(r"^\* `([^`]*)` - (.+)$", re.MULTILINE)
+DECIMALS = re.compile(r"\\\.\\d\{0,(\d+)\}")
+# Django's integer field bounds: every integer has them, they say nothing.
+INT32 = (-2147483648, 2147483647)
+PAGE_FIELDS = {"count", "next", "previous", "results"}
+
+
+def find_route(schema, route):
+    """The schema's path for a route as a person or an agent types it: with
+    real ids (work-orders/1234/) or the placeholders `operx api rutas` prints
+    ({pk}). A fixed word beats a placeholder, so items/siguiente-codigo/
+    isn't items/{pk}/. LookupError when no route fits."""
+    wanted = _segments(route)
+    best = None
+    for path in schema.get("paths", {}):
+        segments = _segments(path)
+        if len(segments) != len(wanted):
+            continue
+        fixed = 0
+        for template, given in zip(segments, wanted):
+            if template.startswith("{"):
+                continue
+            if template != given:
+                break
+            fixed += 1
+        else:
+            if best is None or fixed > best[0]:
+                best = (fixed, path)
+    if best is None:
+        raise LookupError(route)
+    return best[1]
+
+
+def _segments(route):
+    route = route.strip().split("?")[0].strip("/")
+    route = route.removeprefix("api/v1/")
+    return route.split("/")
+
+
+def describe(schema, path, method=None):
+    """Each operation of the route (or only `method`): a dict an agent reads
+    as JSON and `operx api campos` prints as tables."""
+    components = schema.get("components", {}).get("schemas", {})
+    operations = schema["paths"][path]
+    described = []
+    for name in METHODS:
+        if name not in operations or (method and method.lower() != name):
+            continue
+        operation = operations[name]
+        parameters = operation.get("parameters", [])
+        body_schema, sending = _body(operation)
+        described.append({
+            "metodo": name.upper(),
+            "ruta": path.removeprefix("/api/v1/"),
+            "descripcion": (operation.get("description") or "").strip(),
+            "en_la_ruta": [_parameter(components, parameter) for parameter in parameters if parameter.get("in") == "path"],
+            "filtros": [_parameter(components, parameter) for parameter in parameters if parameter.get("in") == "query"],
+            "datos": _fields(components, body_schema) if body_schema else [],
+            "envio": sending if body_schema else None,
+            "responde": _answer(components, operation),
+        })
+    return described
+
+
+def methods_of(schema, path):
+    return [name.upper() for name in METHODS if name in schema["paths"][path]]
+
+
+def _body(operation):
+    """The body's schema and how it goes: JSON (-d), or a form with a file
+    (-a for the file, -d for the rest)."""
+    content = operation.get("requestBody", {}).get("content", {})
+    if "application/json" in content:
+        return content["application/json"].get("schema"), "json"
+    for kind in ("multipart/form-data", "application/x-www-form-urlencoded"):
+        if kind in content:
+            return content[kind].get("schema"), "archivos"
+    return None, None
+
+
+def _resolve(components, node):
+    """A field's schema with its $ref, its one-ref allOf and its
+    enum-or-blank-or-null oneOf followed. What the wrapper says (nullable,
+    readOnly, its own description) stays; an enum's description becomes
+    its labels."""
+    node = dict(node or {})
+    if "$ref" in node:
+        name = node.pop("$ref").split("/")[-1]
+        target = _labelled(components.get(name, {}))
+        node = {**target, **node, "_name": name}
+    if len(node.get("allOf", [])) == 1:
+        inner = _resolve(components, node.pop("allOf")[0])
+        node = {**inner, **node}
+    if "oneOf" in node:
+        choices = [_resolve(components, choice) for choice in node.pop("oneOf")]
+        kept = []
+        for choice in choices:
+            if choice.get("enum") == [""] or choice.get("maxLength") == 0:
+                node["_blank"] = True
+            elif choice.get("enum") == [None]:
+                node["nullable"] = True
+            else:
+                kept.append(choice)
+        if kept:
+            node = {**kept[0], **node}
+    if node.get("type") == "array" and "items" in node:
+        # One level only: a record's own fields are followed by _fields.
+        node["items"] = _resolve(components, node["items"]) if "$ref" in node["items"] else node["items"]
+    return node
+
+
+def _labelled(node):
+    """An enum's "* `low` - Baja" description as its labels."""
+    if "enum" not in node:
+        return node
+    node = dict(node)
+    labels = dict(LABEL_LINE.findall(node.pop("description", "") or ""))
+    node["_labels"] = labels
+    return node
+
+
+def _fields(components, body_schema, prefix="", depth=0, seen=frozenset()):
+    record = _resolve(components, body_schema)
+    required = set(record.get("required", []))
+    rows = []
+    for name, value in record.get("properties", {}).items():
+        field = _resolve(components, value)
+        if field.get("readOnly"):
+            continue
+        path = prefix + name
+        rows.append(_row(path, field, name in required))
+        if depth >= MAX_DEPTH:
+            continue
+        if field.get("type") == "array":
+            items = _resolve(components, field.get("items"))
+            if "properties" in items and items.get("_name") not in seen:
+                rows.extend(_fields(components, items, f"{path}[].", depth + 1, seen | {items.get("_name")}))
+        elif "properties" in field and field.get("_name") not in seen:
+            rows.extend(_fields(components, field, f"{path}.", depth + 1, seen | {field.get("_name")}))
+    return rows
+
+
+def _row(name, field, required):
+    """One field: its JSON type and format, and only what applies to it."""
+    row = {"campo": name, "tipo": field.get("type") or ("string" if "enum" in field else None), "obligatorio": required}
+    if field.get("format"):
+        row["formato"] = field["format"]
+    if field.get("type") == "array":
+        items = field.get("items") or {}
+        row["de"] = "object" if "properties" in items else items.get("type") or ("string" if "enum" in items else None)
+    values = _values(field)
+    if field.get("type") == "array" and not values:
+        values = _values(field.get("items") or {})
+    if values:
+        row["valores"] = values
+    if field.get("nullable"):
+        row["nulo"] = True
+    if field.get("_blank"):
+        row["vacio"] = True
+    if "default" in field:
+        row["por_defecto"] = field["default"]
+    if field.get("maxLength"):
+        row["maximo_largo"] = field["maxLength"]
+    for key, label in (("minimum", "minimo"), ("maximum", "maximo")):
+        if key in field and field[key] not in INT32:
+            row[label] = field[key]
+    decimals = DECIMALS.search(field.get("pattern", "")) if field.get("format") == "decimal" else None
+    if decimals:
+        row["decimales"] = int(decimals.group(1))
+    if field.get("description"):
+        row["nota"] = field["description"].strip()
+    return row
+
+
+def _values(field):
+    labels = field.get("_labels") or {}
+    values = [value for value in field.get("enum", []) if value not in (None, "")]
+    return [{"valor": value, "etiqueta": labels.get(value, value)} for value in values]
+
+
+def _parameter(components, parameter):
+    """A filter or a value in the address. A filter's labels come in its own
+    description, not in its schema's."""
+    field = _resolve(components, parameter.get("schema"))
+    description = (parameter.get("description") or "").strip()
+    labels = dict(LABEL_LINE.findall(description))
+    if "enum" in field and labels:
+        field["_labels"] = labels
+        description = ""
+    if description:
+        field["description"] = description
+    row = _row(parameter["name"], field, bool(parameter.get("required")))
+    if parameter.get("in") == "path":
+        # Only the name and type: it's written in the address itself.
+        return {key: row[key] for key in ("campo", "tipo", "obligatorio")}
+    return row
+
+
+def _answer(components, operation):
+    """What a call answers: its status, whether it comes by pages, and the
+    names of a record's fields."""
+    for status, response in operation.get("responses", {}).items():
+        if not status.startswith("2"):
+            continue
+        schema = (response.get("content", {}).get("application/json") or {}).get("schema")
+        if schema is None:
+            return {"estado": int(status), "pagina": False, "campos": []}
+        record = _resolve(components, schema)
+        paged = PAGE_FIELDS <= set(record.get("properties", {}))
+        if paged:
+            record = _resolve(components, record["properties"]["results"])
+        if record.get("type") == "array":
+            record = _resolve(components, record.get("items"))
+        return {"estado": int(status), "pagina": paged, "campos": list(record.get("properties", {}))}
+    return {"estado": None, "pagina": False, "campos": []}

{operx_cli-0.5.0 → operx_cli-0.6.0}/operx_cli/commands/ambiental.py

@@ -15,12 +15,14 @@ from .common import (
     CsvOption,
     JsonOption,
     YesOption,
+    answer_of,
     client_of,
     confirm_write,
     day,
     month,
     number,
     output_format,
+    print_result,
 )
 from .empresas import (
     ENVIRONMENT,
@@ -71,9 +73,10 @@ def nueva_accion(
     tipo: Annotated[TipoAccion, typer.Option("--tipo")] = TipoAccion.correctiva,
     empresa: EmpresaOption = None,
     si: YesOption = False,
+    as_json: JsonOption = False,
 ):
     """Agrega una acción al plan de acción ambiental."""
-    create_action(ctx, ENVIRONMENT, titulo, para, responsable, tipo, empresa, si)
+    create_action(ctx, ENVIRONMENT, titulo, para, responsable, tipo, empresa, si, as_json)
 
 
 @app.command("accion-hecha")
@@ -83,9 +86,10 @@ def accion_hecha(
     evidencia: Annotated[str, typer.Option("--evidencia", help="Qué se hizo.")],
     empresa: EmpresaOption = None,
     si: YesOption = False,
+    as_json: JsonOption = False,
 ):
     """Marca hecha una acción, con lo que se hizo. Verificarla se hace en la app."""
-    mark_done(ctx, ENVIRONMENT, accion, evidencia, empresa, si)
+    mark_done(ctx, ENVIRONMENT, accion, evidencia, empresa, si, as_json)
 
 
 @app.command()
@@ -126,6 +130,7 @@ def residuo(
     sede: Annotated[Optional[str], typer.Option("--sede", help="La sede, si dos tienen una corriente con ese nombre.")] = None,
     empresa: EmpresaOption = None,
     si: YesOption = False,
+    as_json: JsonOption = False,
 ):
     """Registra los kilos de residuos generados (pesados)."""
     client = client_of(ctx)
@@ -133,8 +138,8 @@ def residuo(
     stream = _stream(client, path, corriente, sede)
     entry = {"stream": stream["id"], "date": day(fecha) or date.today().isoformat(), "kg": number(kg)}
     confirm_write(f"Registrar {kg} kg de «{stream['name']}» el {shown_moment(entry['date'])}.", si)
-    client.send("POST", f"{path}/waste/entries", json=entry)
-    typer.echo(f"Registrados {kg} kg de {stream['name']}.")
+    recorded = answer_of(client.send("POST", f"{path}/waste/entries", json=entry))
+    print_result(recorded, as_json, f"Registrados {kg} kg de {stream['name']}.")
 
 
 def _stream(client, path, corriente, sede):
@@ -163,6 +168,7 @@ def lectura(
     fecha: FechaOption = None,
     empresa: EmpresaOption = None,
     si: YesOption = False,
+    as_json: JsonOption = False,
 ):
     """Registra la lectura de un medidor (agua, energía, gas)."""
     client = client_of(ctx)
@@ -170,5 +176,5 @@ def lectura(
     meter = find_in(client.get(f"{path}/consumption/meters"), medidor, ["name", "meter_name"], "medidor")
     reading = {"source": meter["id"], "read_on": day(fecha) or date.today().isoformat(), "value": number(valor)}
     confirm_write(f"Lectura {valor} en «{meter['name']}» el {shown_moment(reading['read_on'])}.", si)
-    client.send("POST", f"{path}/consumption/readings", json=reading)
-    typer.echo(f"Lectura registrada: {valor} en {meter['name']}.")
+    recorded = answer_of(client.send("POST", f"{path}/consumption/readings", json=reading))
+    print_result(recorded, as_json, f"Lectura registrada: {valor} en {meter['name']}.")

{operx_cli-0.5.0 → operx_cli-0.6.0}/operx_cli/commands/articulos.py

@@ -10,7 +10,7 @@ from ..lookup import NoSingleMatch, find_in, find_one
 from ..output import cell_text, print_card, print_record, print_rows
 from .common import (
     AllOption, CliError, CsvOption, JsonOption, SearchOption, YesOption, client_of, confirm_write, list_rows,
-    output_format, without_empty,
+    output_format, print_result, without_empty,
 )
 
 app = typer.Typer(help="Artículos (Inventario): los repuestos, consumibles y herramientas que manejas.", no_args_is_help=True)
@@ -98,6 +98,7 @@ def crear(
     fabricante: Annotated[Optional[str], typer.Option("--fabricante")] = None,
     referencia: Annotated[Optional[str], typer.Option("--referencia", help="La referencia del fabricante.")] = None,
     si: YesOption = False,
+    as_json: JsonOption = False,
 ):
     """Crea un artículo en el catálogo. Lo que hay se carga después con `inventario entrada`."""
     client = client_of(ctx)
@@ -119,7 +120,9 @@ def crear(
     })
     confirm_write(f"Crear el artículo «{nombre}».", si)
     created = client.send("POST", "inventory/items", json=item).json()
-    typer.echo(f"Artículo {created['code']} creado: {created['name']}.")
+    print_result(created, as_json, f"Artículo {created['code']} creado: {created['name']}.")
+    if as_json:
+        return
     typer.echo(
         f"Para cargar lo que hay: operx inventario entrada --articulo {created['code']} --lugar … --cantidad … --costo-unitario …"
     )

{operx_cli-0.5.0 → operx_cli-0.6.0}/operx_cli/commands/avisos.py

@@ -14,11 +14,13 @@ from .common import (
     CsvOption,
     JsonOption,
     YesOption,
+    answer_of,
     client_of,
     confirm_write,
     day,
     list_rows,
     output_format,
+    print_result,
 )
 
 NOTICE_COLUMNS = [("when", "Cuándo"), ("title", "Aviso"), ("body", "Detalle"), ("read", "Leído")]
@@ -40,8 +42,8 @@ def avisos(
     client = client_of(ctx)
     if marcar_leidos:
         confirm_write("Marcar todos tus avisos como leídos.", si)
-        client.send("POST", "notifications/mark-read")
-        typer.echo("Listo: no te quedan avisos sin leer.")
+        marked = answer_of(client.send("POST", "notifications/mark-read"))
+        print_result(marked, as_json, "Listo: no te quedan avisos sin leer.")
         return
     output = output_format(as_json, as_csv)
     rows = list_rows(client, "notifications", {"is_read": None if todos else "false"}, todas)

{operx_cli-0.5.0 → operx_cli-0.6.0}/operx_cli/commands/common.py

@@ -12,7 +12,7 @@ import typer
 
 from .. import settings
 from ..client import ApiClient
-from ..output import note
+from ..output import json_text, note
 from ..values import decimal_text, iso_date, iso_datetime, month_text
 
 NOT_SIGNED_IN = "No has entrado en este perfil. Escribe `operx login`."
@@ -103,7 +103,8 @@ def confirm_write(what, yes):
     if not can_ask():
         raise CliError(NEEDS_SI)
     try:
-        answer = typer.prompt(f"{what} ¿Confirmas? (s/n)", default="n", show_default=False)
+        # On stderr: `operx … --json | jq` must get only the API's answer.
+        answer = typer.prompt(f"{what} ¿Confirmas? (s/n)", default="n", show_default=False, err=True)
     except typer.Abort:
         raise CliError(NEEDS_SI) from None
     if answer.strip().casefold() not in YES_ANSWERS:
@@ -147,3 +148,22 @@ def month(text):
 def without_empty(fields):
     """The fields someone gave: an option left out isn't sent."""
     return {key: value for key, value in fields.items() if value not in (None, "")}
+
+
+def answer_of(response):
+    """A write's answer as JSON; {} when the API sent nothing back."""
+    if not response.content:
+        return {}
+    try:
+        return response.json()
+    except ValueError:
+        return {}
+
+
+def print_result(answer, as_json, message):
+    """What a write did. With --json, only the API's answer (the new record,
+    its id), for a script or an AI agent to read; else a line for a person."""
+    if as_json:
+        typer.echo(json_text(answer))
+        return
+    typer.echo(message)

{operx_cli-0.5.0 → operx_cli-0.6.0}/operx_cli/commands/empresas.py

@@ -12,7 +12,7 @@ import typer
 from ..lookup import find_in
 from ..output import note, print_rows
 from ..values import shown_moment
-from .common import CliError, client_of, confirm_write, day
+from .common import CliError, answer_of, client_of, confirm_write, day, print_result
 
 
 @dataclass(frozen=True)
@@ -115,7 +115,7 @@ def print_actions(client, product, empresa, estado, output):
     print_rows(ACTION_COLUMNS, actions, output)
 
 
-def create_action(ctx, product, titulo, para, responsable, tipo, empresa, si):
+def create_action(ctx, product, titulo, para, responsable, tipo, empresa, si, as_json=False):
     client = client_of(ctx)
     path = company_path(client, product, empresa)
     owner_id, owner_name = owner_of(client, responsable)
@@ -126,12 +126,12 @@ def create_action(ctx, product, titulo, para, responsable, tipo, empresa, si):
         action["owner_name"] = owner_name
     confirm_write(f"Crear la acción «{titulo}», para el {shown_moment(action['due_on'])}, a cargo de {responsable}.", si)
     created = client.send("POST", f"{path}/actions", json=action).json()
-    typer.echo(f"Acción {created['id']} creada: {created.get(product.title_field, titulo)}.")
+    print_result(created, as_json, f"Acción {created['id']} creada: {created.get(product.title_field, titulo)}.")
 
 
-def mark_done(ctx, product, accion, evidencia, empresa, si):
+def mark_done(ctx, product, accion, evidencia, empresa, si, as_json=False):
     client = client_of(ctx)
     path = company_path(client, product, empresa)
     confirm_write(f"Marcar hecha la acción {accion}.", si)
-    client.send("POST", f"{path}/actions/{accion}/done", json={"evidence": evidencia})
-    typer.echo(f"Acción {accion} hecha.")
+    done = answer_of(client.send("POST", f"{path}/actions/{accion}/done", json={"evidence": evidencia}))
+    print_result(done, as_json, f"Acción {accion} hecha.")