operx-cli 0.1.0__tar.gz

operx_cli-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: operx-cli
+Version: 0.1.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
+Requires-Dist: typer>=0.27
+Requires-Dist: httpx>=0.28
+Requires-Dist: keyring>=25
+Requires-Dist: openpyxl>=3.1
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# operx: OperX desde la terminal
+
+`operx` usa la API de OperX con tu token personal: lo mismo que puedes hacer
+en la app, desde una terminal, un script o una tarea programada. Actúa como
+tú, con tu rol, y solo en tu empresa.
+
+## Instalar
+
+Necesitas Python 3.10 o más nuevo.
+
+```sh
+pipx install ./cli          # desde esta carpeta del repositorio
+operx --version
+```
+
+## Entrar
+
+1. En la app, abre el menú de tu cuenta › **Acceso por API** y crea un token.
+   Elige *Lectura y escritura* si vas a crear o cambiar datos.
+2. Guárdalo en tu equipo:
+
+   ```sh
+   operx entrar        # pega el token; no se muestra
+   operx cuenta        # quién eres, tu empresa y tu rol
+   ```
+
+El token queda en el llavero del sistema (en Windows, el Administrador de
+credenciales), nunca en un archivo. En un servidor sin llavero, usa variables
+de entorno: `OPERX_TOKEN` (el token) y, si no es producción, `OPERX_DIRECCION`.
+
+Para otra dirección u otra empresa, usa un perfil:
+
+```sh
+operx --perfil pruebas entrar --direccion https://…
+operx --perfil pruebas ordenes listar
+```
+
+`operx salir` borra el token de este equipo; para que deje de funcionar,
+revócalo en Acceso por API.
+
+## Comandos
+
+```sh
+operx buscar "bomba"                       # como la barra de búsqueda de la app
+
+operx ordenes listar --estado en-progreso --asignada-a yo
+operx ordenes ver 1234
+operx ordenes crear --titulo "Cambio de rodamiento" --equipo BOM-04 --prioridad alta --vence 30/10/2026
+operx ordenes estado 1234 completada
+operx ordenes asignar 1234 "Pedro Pérez"
+operx ordenes comentar 1234 "Llegó el repuesto"
+
+operx equipos listar --buscar compresor
+operx equipos ver BOM-04
+operx equipos crear --nombre "Bomba 4" --codigo BOM-04 --lugar "Planta Norte"
+operx clientes listar
+operx clientes crear --nombre "Acme S.A.S." --nit 900123456
+operx clientes crear --nombre "Filtros Ltda" --rol proveedor
+operx lugares listar
+
+operx inventario existencias --buscar filtro
+operx inventario entrada --articulo FIL-010 --lugar "Bodega central" --cantidad 10 --costo-unitario 1.500,50
+operx inventario salida --articulo FIL-010 --lugar "Bodega central" --cantidad 2 --motivo Consumo
+
+operx lecturas puntos BOM-04
+operx lecturas registrar --punto 12 --valor 73,4
+
+operx personas importar empleados.xlsx               # revisa el archivo, no guarda
+operx personas importar empleados.xlsx --confirmar   # guarda si ninguna fila tiene errores
+```
+
+`operx --help` y `operx ordenes --help` muestran todas las opciones.
+
+- Los equipos, lugares, clientes, artículos y personas se nombran por su
+  código o su nombre exacto. Si dos se llaman igual, `operx` lo dice y pide
+  el id.
+- Los números y las fechas se escriben como en la app: `73,4`, `1.500,50`,
+  `30/10/2026`, `22/10/2026 08:00`.
+- Las listas muestran la primera página; `--todas` las trae todas.
+- `--json` da todo lo que responde la API; `--csv` da un CSV que Excel abre
+  bien (`operx equipos listar --todas --csv > equipos.csv`).
+
+### 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
+el historial del token (Acceso por API › el token › Actividad) marcada como
+hecha desde la CLI.
+
+### Importar personas
+
+La primera columna con el nombre basta. `operx` reconoce las columnas
+Nombres, Apellidos, Código, Cargo, Tipo de contrato, Fecha de ingreso, Fin de
+contrato, Celular, Sede y las de contacto de emergencia, con o sin tildes.
+Una columna con otro nombre se indica con `--mapa "Tu columna=campo"`.
+Nadie recibe acceso a la app al importarlo: las invitaciones se envían en
+Usuarios y acceso.
+
+### Cualquier otra llamada
+
+Lo que no tiene comando propio se hace con `operx api`, con las direcciones
+de Acceso por API › Documentación (sin `/api/v1/`):
+
+```sh
+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 api POST work-orders/1234/attachments/ -a file=foto.jpg -d '{"file_type": "photo"}'
+```
+
+En Git Bash, una dirección que empieza por `/` se vuelve una ruta de Windows:
+escríbela sin la barra inicial, como arriba.
+
+## Para desarrollar
+
+```sh
+cd cli
+python -m venv .venv && .venv/Scripts/python -m pip install -e ".[test]"
+.venv/Scripts/python -m pytest
+```
+
+`operx_cli/client.py` es lo único que habla con la red; el servidor MCP lo
+usará igual.

operx_cli-0.1.0/README.md

@@ -0,0 +1,123 @@
+# operx: OperX desde la terminal
+
+`operx` usa la API de OperX con tu token personal: lo mismo que puedes hacer
+en la app, desde una terminal, un script o una tarea programada. Actúa como
+tú, con tu rol, y solo en tu empresa.
+
+## Instalar
+
+Necesitas Python 3.10 o más nuevo.
+
+```sh
+pipx install ./cli          # desde esta carpeta del repositorio
+operx --version
+```
+
+## Entrar
+
+1. En la app, abre el menú de tu cuenta › **Acceso por API** y crea un token.
+   Elige *Lectura y escritura* si vas a crear o cambiar datos.
+2. Guárdalo en tu equipo:
+
+   ```sh
+   operx entrar        # pega el token; no se muestra
+   operx cuenta        # quién eres, tu empresa y tu rol
+   ```
+
+El token queda en el llavero del sistema (en Windows, el Administrador de
+credenciales), nunca en un archivo. En un servidor sin llavero, usa variables
+de entorno: `OPERX_TOKEN` (el token) y, si no es producción, `OPERX_DIRECCION`.
+
+Para otra dirección u otra empresa, usa un perfil:
+
+```sh
+operx --perfil pruebas entrar --direccion https://…
+operx --perfil pruebas ordenes listar
+```
+
+`operx salir` borra el token de este equipo; para que deje de funcionar,
+revócalo en Acceso por API.
+
+## Comandos
+
+```sh
+operx buscar "bomba"                       # como la barra de búsqueda de la app
+
+operx ordenes listar --estado en-progreso --asignada-a yo
+operx ordenes ver 1234
+operx ordenes crear --titulo "Cambio de rodamiento" --equipo BOM-04 --prioridad alta --vence 30/10/2026
+operx ordenes estado 1234 completada
+operx ordenes asignar 1234 "Pedro Pérez"
+operx ordenes comentar 1234 "Llegó el repuesto"
+
+operx equipos listar --buscar compresor
+operx equipos ver BOM-04
+operx equipos crear --nombre "Bomba 4" --codigo BOM-04 --lugar "Planta Norte"
+operx clientes listar
+operx clientes crear --nombre "Acme S.A.S." --nit 900123456
+operx clientes crear --nombre "Filtros Ltda" --rol proveedor
+operx lugares listar
+
+operx inventario existencias --buscar filtro
+operx inventario entrada --articulo FIL-010 --lugar "Bodega central" --cantidad 10 --costo-unitario 1.500,50
+operx inventario salida --articulo FIL-010 --lugar "Bodega central" --cantidad 2 --motivo Consumo
+
+operx lecturas puntos BOM-04
+operx lecturas registrar --punto 12 --valor 73,4
+
+operx personas importar empleados.xlsx               # revisa el archivo, no guarda
+operx personas importar empleados.xlsx --confirmar   # guarda si ninguna fila tiene errores
+```
+
+`operx --help` y `operx ordenes --help` muestran todas las opciones.
+
+- Los equipos, lugares, clientes, artículos y personas se nombran por su
+  código o su nombre exacto. Si dos se llaman igual, `operx` lo dice y pide
+  el id.
+- Los números y las fechas se escriben como en la app: `73,4`, `1.500,50`,
+  `30/10/2026`, `22/10/2026 08:00`.
+- Las listas muestran la primera página; `--todas` las trae todas.
+- `--json` da todo lo que responde la API; `--csv` da un CSV que Excel abre
+  bien (`operx equipos listar --todas --csv > equipos.csv`).
+
+### 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
+el historial del token (Acceso por API › el token › Actividad) marcada como
+hecha desde la CLI.
+
+### Importar personas
+
+La primera columna con el nombre basta. `operx` reconoce las columnas
+Nombres, Apellidos, Código, Cargo, Tipo de contrato, Fecha de ingreso, Fin de
+contrato, Celular, Sede y las de contacto de emergencia, con o sin tildes.
+Una columna con otro nombre se indica con `--mapa "Tu columna=campo"`.
+Nadie recibe acceso a la app al importarlo: las invitaciones se envían en
+Usuarios y acceso.
+
+### Cualquier otra llamada
+
+Lo que no tiene comando propio se hace con `operx api`, con las direcciones
+de Acceso por API › Documentación (sin `/api/v1/`):
+
+```sh
+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 api POST work-orders/1234/attachments/ -a file=foto.jpg -d '{"file_type": "photo"}'
+```
+
+En Git Bash, una dirección que empieza por `/` se vuelve una ruta de Windows:
+escríbela sin la barra inicial, como arriba.
+
+## Para desarrollar
+
+```sh
+cd cli
+python -m venv .venv && .venv/Scripts/python -m pip install -e ".[test]"
+.venv/Scripts/python -m pytest
+```
+
+`operx_cli/client.py` es lo único que habla con la red; el servidor MCP lo
+usará igual.

operx_cli-0.1.0/operx_cli/__init__.py

@@ -0,0 +1,5 @@
+"""OperX's command line (PRODUCT_ROADMAP.md › Platform, step 3): the public
+API (backend/users/api_allowlist.py) from a terminal, with a personal API
+token."""
+
+__version__ = "0.1.0"

operx_cli-0.1.0/operx_cli/app.py

@@ -0,0 +1,87 @@
+"""`operx`: the root of the commands, and what turns a refused call into
+one line instead of a traceback."""
+
+import sys
+from typing import Annotated, Optional
+
+import typer
+from typer.core import TyperGroup
+
+from . import __version__, settings
+from .client import ApiError
+from .commands import account, inventario, lecturas, ordenes, personas, raw, registros, search
+from .commands.common import CliError, Session
+from .lookup import NoSingleMatch
+from .spreadsheet import SpreadsheetError
+
+# What a person can fix: shown as "Error: …", exit code 1.
+EXPECTED_ERRORS = (ApiError, CliError, NoSingleMatch, SpreadsheetError, settings.SettingsError)
+
+
+class ReportedErrors(TyperGroup):
+    def invoke(self, ctx):
+        try:
+            return super().invoke(ctx)
+        except EXPECTED_ERRORS as error:
+            typer.echo(f"Error: {error}", err=True)
+            raise typer.Exit(1) from None
+        except typer.Abort:
+            # Ctrl+C, or a question whose answer never came.
+            typer.echo("Se canceló.", err=True)
+            raise typer.Exit(1) from None
+
+
+app = typer.Typer(
+    cls=ReportedErrors,
+    help="OperX desde la terminal: tu empresa con tu token de API.",
+    no_args_is_help=True,
+    add_completion=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    # A crash must never print the token, which lives in the client's locals.
+    pretty_exceptions_show_locals=False,
+)
+
+
+def _show_version(value):
+    if value:
+        typer.echo(f"operx {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    ctx: typer.Context,
+    perfil: Annotated[
+        Optional[str],
+        typer.Option("--perfil", "-p", help="El perfil: otra API u otra empresa. Sin él, «principal» (o OPERX_PERFIL)."),
+    ] = None,
+    version: Annotated[
+        bool, typer.Option("--version", callback=_show_version, is_eager=True, help="La versión instalada.")
+    ] = False,
+):
+    if ctx.obj is None:
+        ctx.obj = Session()
+    ctx.obj.profile = settings.profile_name(perfil)
+
+
+app.command()(account.entrar)
+app.command()(account.salir)
+app.command()(account.cuenta)
+app.command()(search.buscar)
+app.command()(raw.api)
+app.add_typer(ordenes.app, name="ordenes")
+app.add_typer(registros.equipos, name="equipos")
+app.add_typer(registros.clientes, name="clientes")
+app.add_typer(registros.lugares, name="lugares")
+app.add_typer(inventario.app, name="inventario")
+app.add_typer(lecturas.app, name="lecturas")
+app.add_typer(personas.app, name="personas")
+
+
+def main():
+    # Redirected to a file, Windows would write the results in its own code
+    # page; the CSV and the JSON are UTF-8.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    app()

operx_cli-0.1.0/operx_cli/client.py

@@ -0,0 +1,134 @@
+"""The calls to OperX's API, with a personal API token: the only module that
+talks to the network. The MCP server can use it as it is.
+
+A write carries an Idempotency-Key, so the views that honour it (stock
+moves, a work order's status, Ambiental's records) never do it twice. Only a
+429 is repeated by itself: it changed nothing. A write that timed out or
+failed on the server is never repeated, because on a view without the key a
+second try could create the record twice.
+"""
+
+import time
+import uuid
+
+import httpx
+
+from . import __version__
+
+USER_AGENT = f"operx-cli/{__version__}"
+WRITES = ("POST", "PUT", "PATCH", "DELETE")
+# A list asks for this many rows a page: the API's cap (utils/pagination.py).
+PAGE_SIZE = 200
+# How many times a 429 is waited out before giving up, and the longest wait.
+RETRIES_ON_429 = 3
+LONGEST_WAIT = 60
+
+SIGN_IN_AGAIN = "Entra de nuevo con `operx entrar`."
+TIMED_OUT_WRITE = (
+    "La API no respondió a tiempo. Revisa en la app si el cambio quedó hecho antes de repetirlo."
+)
+
+
+class ApiError(Exception):
+    """An answer the API refused, or no answer at all (status 0)."""
+
+    def __init__(self, status, message):
+        super().__init__(message)
+        self.status = status
+
+
+def api_path(path):
+    """'/api/v1/work-orders/12' → 'work-orders/12/': the part after /api/v1/,
+    with the trailing slash Django's addresses need."""
+    path = path.strip().lstrip("/")
+    if path.startswith("api/v1/"):
+        path = path[len("api/v1/"):]
+    address, separator, query = path.partition("?")
+    if not address.endswith("/"):
+        address += "/"
+    return address + separator + query
+
+
+def error_message(response):
+    """The API's own words: its "detail", or each field with its errors."""
+    try:
+        body = response.json()
+    except ValueError:
+        return f"La API respondió {response.status_code}."
+    if isinstance(body, dict) and isinstance(body.get("detail"), str):
+        return body["detail"]
+    if isinstance(body, dict) and body:
+        lines = []
+        for field, errors in body.items():
+            text = " ".join(str(error) for error in errors) if isinstance(errors, list) else str(errors)
+            lines.append(f"{field}: {text}")
+        return "\n".join(lines)
+    return f"La API respondió {response.status_code}."
+
+
+def seconds_to_wait(response):
+    try:
+        return min(int(response.headers.get("Retry-After", "5")), LONGEST_WAIT)
+    except ValueError:
+        return 5
+
+
+class ApiClient:
+    def __init__(self, address, token, transport=None, sleep=time.sleep):
+        self.address = address.rstrip("/")
+        self.sleep = sleep
+        self.http = httpx.Client(
+            base_url=self.address + "/api/v1/",
+            headers={"Authorization": f"Bearer {token}", "User-Agent": USER_AGENT, "Accept": "application/json"},
+            timeout=60,
+            transport=transport,
+        )
+
+    def send(self, method, path, params=None, json=None, files=None, data=None):
+        """One call; its answer, or ApiError when the API refused it."""
+        method = method.upper()
+        headers = {"Idempotency-Key": str(uuid.uuid4())} if method in WRITES else {}
+        waits = 0
+        while True:
+            response = self._request(method, path, params, json, files, data, headers)
+            if response.status_code != 429 or waits == RETRIES_ON_429:
+                break
+            self.sleep(seconds_to_wait(response))
+            waits += 1
+        if response.status_code >= 400:
+            message = error_message(response)
+            if response.status_code == 401:
+                message = f"{message}\n{SIGN_IN_AGAIN}"
+            raise ApiError(response.status_code, message)
+        return response
+
+    def _request(self, method, path, params, json, files, data, headers):
+        try:
+            return self.http.request(
+                method, api_path(path), params=params, json=json, files=files, data=data, headers=headers,
+            )
+        except httpx.TimeoutException:
+            if method in WRITES:
+                raise ApiError(0, TIMED_OUT_WRITE)
+            raise ApiError(0, "La API no respondió a tiempo. Intenta de nuevo.")
+        except httpx.HTTPError as error:
+            raise ApiError(0, f"No se pudo conectar con {self.address}: {error}")
+
+    def get(self, path, params=None):
+        """A read's answer, as JSON."""
+        return self.send("GET", path, params=params).json()
+
+    def all_pages(self, path, params):
+        """Every row of a list, page by page. An address that isn't paginated
+        answers a plain list, taken as it comes. The pages are asked by number:
+        the "next" the API sends can name the wrong host behind Cloudflare."""
+        page = 1
+        rows = []
+        while True:
+            answer = self.get(path, {**params, "page": page, "page_size": PAGE_SIZE})
+            if isinstance(answer, list):
+                return answer
+            rows.extend(answer.get("results", []))
+            if not answer.get("next"):
+                return rows
+            page += 1

operx_cli-0.1.0/operx_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""One module per group of commands: `operx ordenes …`, `operx equipos …`."""

operx_cli-0.1.0/operx_cli/commands/account.py

@@ -0,0 +1,68 @@
+"""`operx entrar`, `operx salir` and `operx cuenta`: the token of a profile,
+and who it acts as."""
+
+from typing import Annotated, Optional
+
+import typer
+
+from .. import settings
+from ..client import ApiClient
+from ..output import print_record
+from .common import CliError, JsonOption, Session, client_of
+
+TOKEN_PREFIX = "opx_"
+PRODUCT_LABELS = {
+    "maintenance": "Trabajos", "people": "Personas", "inventory": "Inventario",
+    "equipment": "Equipos", "sst": "SG-SST", "environment": "Ambiental",
+}
+
+
+def full_name(me):
+    return " ".join(f"{me.get('first_name', '')} {me.get('last_name', '')}".split()) or me.get("email", "")
+
+
+def entrar(
+    ctx: typer.Context,
+    direccion: Annotated[
+        Optional[str], typer.Option("--direccion", help="La dirección de la API. Sin ella, la de producción.")
+    ] = None,
+):
+    """Guarda tu token de API en el llavero del sistema. Créalo en la app: menú de tu cuenta › Acceso por API."""
+    session = ctx.find_object(Session)
+    token = typer.prompt("Pega tu token (no se mostrará)", hide_input=True).strip()
+    if not token.startswith(TOKEN_PREFIX):
+        raise CliError("Eso no es un token de OperX: empieza por «opx_». Créalo en la app, en Acceso por API.")
+    address = direccion.rstrip("/") if direccion else session.address()
+    # Checked before it's kept: a token the API refuses is never saved.
+    me = ApiClient(address, token, transport=session.transport).get("auth/me")
+    settings.save_token(session.profile, token)
+    if direccion:
+        settings.save_address(session.profile, address)
+    typer.echo(f"Listo: entraste como {full_name(me)} en {me.get('client_name')}.")
+    typer.echo(f"Perfil «{session.profile}», {address}.")
+
+
+def salir(ctx: typer.Context):
+    """Borra el token de este perfil del llavero. El token sigue vivo: revócalo en Acceso por API si ya no lo usas."""
+    session = ctx.find_object(Session)
+    settings.forget_token(session.profile)
+    typer.echo(f"Se borró el token del perfil «{session.profile}».")
+
+
+def cuenta(ctx: typer.Context, as_json: JsonOption = False):
+    """Quién eres para la API: tu nombre, tu empresa y tu rol."""
+    session = ctx.find_object(Session)
+    me = client_of(ctx).get("auth/me")
+    if as_json:
+        print_record(me, "json")
+        return
+    roles = [me.get("role")] + list(me.get("extra_roles") or [])
+    print_record({
+        "Nombre": full_name(me),
+        "Correo": me.get("email"),
+        "Empresa": me.get("client_name"),
+        "Rol": [role for role in roles if role],
+        "Productos": [PRODUCT_LABELS.get(product, product) for product in me.get("products") or []],
+        "Perfil": session.profile,
+        "Dirección": session.address(),
+    }, "tabla")

operx_cli-0.1.0/operx_cli/commands/common.py

@@ -0,0 +1,116 @@
+"""What every command shares: the session (which profile, which API), the
+options that choose how results are shown, and the question before a
+write."""
+
+import sys
+from dataclasses import dataclass
+from typing import Annotated, Optional
+
+import typer
+
+from .. import settings
+from ..client import ApiClient
+from ..output import note
+from ..values import decimal_text, iso_date, iso_datetime
+
+NOT_SIGNED_IN = "No has entrado en este perfil. Usa `operx entrar` con un token de Acceso por API."
+NEEDS_SI = "Esto cambia datos de tu empresa. Fuera de una terminal agrega --si para confirmarlo."
+
+
+class CliError(Exception):
+    """Something the person typed that can't be done: shown as one line."""
+
+
+@dataclass
+class Session:
+    profile: str = settings.DEFAULT_PROFILE
+    # httpx's transport: None goes to the network; the tests pass a fake API.
+    transport: object = None
+
+    def address(self):
+        return settings.address_of(self.profile)
+
+    def client(self):
+        token = settings.token_of(self.profile)
+        if not token:
+            raise CliError(NOT_SIGNED_IN)
+        return ApiClient(self.address(), token, transport=self.transport)
+
+
+def client_of(ctx):
+    return ctx.find_object(Session).client()
+
+
+JsonOption = Annotated[bool, typer.Option("--json", help="Todo lo que responde la API, en JSON.")]
+CsvOption = Annotated[bool, typer.Option("--csv", help="En CSV para Excel (UTF-8, separado por punto y coma).")]
+AllOption = Annotated[bool, typer.Option("--todas", help="Todas las páginas, no solo la primera.")]
+YesOption = Annotated[bool, typer.Option("--si", help="Escribe sin preguntar (para scripts y tareas programadas).")]
+SearchOption = Annotated[Optional[str], typer.Option("--buscar", help="Solo lo que contenga este texto.")]
+
+
+def output_format(json_flag, csv_flag):
+    if json_flag and csv_flag:
+        raise CliError("Usa --json o --csv, no los dos.")
+    if json_flag:
+        return "json"
+    return "csv" if csv_flag else "tabla"
+
+
+def list_rows(client, path, params, all_pages):
+    """The first page of a list, or every page with --todas."""
+    params = {key: value for key, value in params.items() if value not in (None, "")}
+    if all_pages:
+        return client.all_pages(path, params)
+    answer = client.get(path, params)
+    if isinstance(answer, list):
+        return answer
+    rows = answer.get("results", [])
+    if answer.get("next"):
+        note(f"Mostrando {len(rows)} de {answer.get('count')}. Usa --todas para verlos todos.")
+    return rows
+
+
+YES_ANSWERS = ("s", "si", "sí", "y", "yes")
+
+
+def can_ask():
+    return sys.stdin.isatty()
+
+
+def confirm_write(what, yes):
+    """Ask before changing anything, unless --si. A script can't answer, so
+    it needs --si: without a terminal, or when the answer never comes
+    (Windows' NUL device passes for a terminal)."""
+    if yes:
+        return
+    if not can_ask():
+        raise CliError(NEEDS_SI)
+    try:
+        answer = typer.prompt(f"{what} ¿Confirmas? (s/n)", default="n", show_default=False)
+    except typer.Abort:
+        raise CliError(NEEDS_SI) from None
+    if answer.strip().casefold() not in YES_ANSWERS:
+        raise CliError("No se cambió nada.")
+
+
+def number(text):
+    try:
+        return decimal_text(text)
+    except ValueError as error:
+        raise CliError(str(error)) from None
+
+
+def moment(text):
+    try:
+        return iso_datetime(text)
+    except ValueError as error:
+        raise CliError(str(error)) from None
+
+
+def day(text):
+    return iso_date(text) if text else None
+
+
+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, "")}