recala-cli 0.6.0__py3-none-any.whl

recala_cli/ids.py

@@ -0,0 +1,139 @@
+"""Resolve displayed IDs without guessing, before any resource request or write."""
+
+from __future__ import annotations
+
+import re
+from functools import wraps
+
+from recala_cli.display import display_name
+from recala_cli.endpoints import ARTICLES_LIST, KNOWLEDGE_LIST, PEOPLE_LIST, TOPICS_LIST
+from recala_cli.errors import CliError, ExitCode
+
+TOPIC_SECTIONS = ("up_next", "backlog", "queued", "processing", "other")
+_PREFIX = re.compile(r"[0-9a-f]{8}", re.IGNORECASE)
+_UUID = re.compile(r"[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}", re.IGNORECASE)
+_ARTICLE_PAGE_LIMIT = 10
+
+
+def is_short_id(selector: str) -> bool:
+    return bool(_PREFIX.fullmatch(selector))
+
+
+def validate_id(selector: str, kind: str) -> None:
+    if not (_UUID.fullmatch(selector) or is_short_id(selector)):
+        command = "article" if kind == "article" else "topics"
+        article = "an" if kind == "article" else "a"
+        raise CliError(ExitCode.USAGE, f"invalid_{kind}_id",
+                       f"{selector} is not {article} {kind} id. Use the 8-character id or the full id from recala {command} list")
+
+
+def id_arguments(**kinds):
+    """Validate before opening a client, which can itself make organization/auth reads."""
+    def decorate(command):
+        @wraps(command)
+        def validated(*args, **kwargs):
+            for argument, kind in kinds.items():
+                value = kwargs[argument]
+                for selector in value if isinstance(value, tuple) else (value,):
+                    validate_id(selector, kind)
+            return command(*args, **kwargs)
+        return validated
+    return decorate
+
+
+def matching_prefix(rows, selector, *, key="id"):
+    return [row for row in rows if str(row[key]).lower().startswith(selector.lower())]
+
+
+def resolve_article_id(client, selector: str) -> str:
+    validate_id(selector, "article")
+    if not is_short_id(selector):
+        return selector
+    matches = {}
+    for page_number in range(_ARTICLE_PAGE_LIMIT):
+        offset = page_number * 100
+        page = client.call(ARTICLES_LIST, params={"limit": 100, "offset": offset})
+        rows = page.get("articles") or []
+        matches.update((row["id"], row) for row in matching_prefix(rows, selector))
+        total = page.get("total")
+        exhausted = offset + 100 >= total if isinstance(total, int) else len(rows) < 100
+        if exhausted:
+            break
+    if not exhausted and len(matches) < 2:
+        raise CliError(ExitCode.USAGE, "article_lookup_incomplete",
+                       "Stopped after 10 pages of articles; a unique match cannot be confirmed. "
+                       "Use the full id from recala article list --json (page with --offset).")
+    if len(matches) > 1:
+        choices = "\n".join(f"{display_name(row.get('article_title') or row.get('topic') or 'Untitled')} [{row['id']}]"
+                            for row in matches.values())
+        cap_notice = "\nStopped after 10 pages; there may be more matches." if not exhausted else ""
+        raise CliError(ExitCode.USAGE, "article_ambiguous", f"Several articles start with {selector}:\n{choices}{cap_notice}")
+    if not matches:
+        raise CliError(ExitCode.USAGE, "article_not_found",
+                       f"No article starts with {selector}. Find its id with: recala article list")
+    return next(iter(matches))
+
+
+def read_topics(client, *, limit=None, offset=0):
+    """Page the base query, preserving Up next order and deduplicating pinned rows."""
+    page_size = limit or 100
+    result = {name: [] for name in TOPIC_SECTIONS}
+    seen = {name: set() for name in TOPIC_SECTIONS}
+    while True:
+        page = client.call(TOPICS_LIST, params={"limit": page_size, "offset": offset})
+        for section in TOPIC_SECTIONS:
+            for row in page.get(section) or []:
+                if row.get("id") not in seen[section]:
+                    result[section].append(row)
+                    seen[section].add(row.get("id"))
+        result["total"] = page.get("total") or 0
+        offset += page_size
+        if limit or offset >= result["total"] or page.get("gated_count"):
+            return result
+
+
+def resolve_topic(data, selector):
+    """Up next accepts exact titles too; ID-only arguments validate separately."""
+    rows = {row["id"]: row for name in TOPIC_SECTIONS for row in data.get(name) or []}
+    if selector in rows:
+        return rows[selector]
+    matches = (matching_prefix(rows.values(), selector) if is_short_id(selector) else
+               [row for row in rows.values() if str(row.get("topic") or "").casefold() == selector.casefold()])
+    if len(matches) != 1:
+        choices = "\n".join(f"{display_name(row['topic'])} [{row['id']}]" for row in matches)
+        raise CliError(ExitCode.USAGE, "topic_ambiguous" if matches else "topic_not_found",
+                       f"{'Several topics match' if matches else 'No topic matches'} {selector}. "
+                       "Use an id from recala topics list.\n" + choices)
+    return matches[0]
+
+
+def resolve_topic_id(client, selector: str) -> str:
+    validate_id(selector, "topic")
+    return resolve_topic(read_topics(client), selector)["id"] if is_short_id(selector) else selector
+
+
+def _resolve_short(client, selector: str, *, endpoint, listed_key: str, noun: str, list_command: str, name_key: str) -> str:
+    """An 8-character prefix of an id the CLI printed, resolved against that list; anything else passes through."""
+    if not is_short_id(selector):
+        return selector
+    rows = (client.call(endpoint) or {}).get(listed_key) or []
+    matches = matching_prefix(rows, selector)
+    if len(matches) == 1:
+        return str(matches[0]["id"])
+    if matches:
+        choices = "\n".join(f"{display_name(row.get(name_key) or 'Unnamed')} [{row['id']}]" for row in matches)
+        raise CliError(ExitCode.USAGE, f"{noun}_ambiguous", f"Several {noun}s start with {selector}:\n{choices}")
+    raise CliError(ExitCode.USAGE, f"{noun}_not_found",
+                   f"No {noun} starts with {selector}. Find its id with: recala {list_command}")
+
+
+def resolve_person_id(client, selector: str) -> str:
+    """An author's 8-character id from `recala authors list`, or the full id."""
+    return _resolve_short(client, selector.strip(), endpoint=PEOPLE_LIST, listed_key="people", noun="author",
+                          list_command="authors list", name_key="display_name")
+
+
+def resolve_source_id(client, selector: str) -> str:
+    """A knowledge source's 8-character id from `recala knowledge list`, or the full id."""
+    return _resolve_short(client, selector.strip(), endpoint=KNOWLEDGE_LIST, listed_key="documents", noun="source",
+                          list_command="knowledge list", name_key="filename")

recala_cli/labels.py

@@ -0,0 +1,74 @@
+"""Best-effort names for human gates, separate from the API's JSON answers."""
+
+from collections.abc import Callable
+from typing import Any
+
+import click
+
+from recala_cli.client import RecalaClient
+from recala_cli.display import display_name
+from recala_cli.endpoints import ARTICLE_SHOW, KEYS_LIST, KNOWLEDGE_LIST, PEOPLE_LIST, TOPIC_WHY
+from recala_cli.errors import CliError
+
+
+def _read_name(client: RecalaClient, kind: str, identifier: str) -> str | None:
+    if kind == "topic":
+        data = client.call(TOPIC_WHY, path={"item_id": identifier})
+        return data.get("topic") if isinstance(data, dict) else None
+    if kind == "article":
+        data = client.call(ARTICLE_SHOW, path={"article_id": identifier})
+        article = data.get("article") if isinstance(data, dict) else None
+        return (article.get("article_title") or article.get("topic")) if isinstance(article, dict) else None
+    endpoint, collection, field = {
+        "person": (PEOPLE_LIST, "people", "display_name"),
+        "key": (KEYS_LIST, "keys", "name"),
+        "source": (KNOWLEDGE_LIST, "documents", "filename"),
+    }[kind]
+    data = client.call(endpoint)
+    rows = data.get(collection) if isinstance(data, dict) else None
+    for row in rows if isinstance(rows, list) else []:
+        if isinstance(row, dict) and str(row.get("id")) == identifier:
+            return row.get(field)
+    return None
+
+
+def resource_label(ctx: click.Context, client: RecalaClient, kind: str, identifier: str,
+                   *, result_subject: bool = True) -> str:
+    """Name first, short id second. Failed reads keep a usable id and never veto a write.
+
+    JSON mode skips presentation reads entirely; pipes still need names. The subject lives in Click's
+    context, so adding a human name cannot change the command's JSON payload.
+    """
+    name = None
+    if not (ctx.find_root().obj or {}).get("as_json"):
+        try:
+            name = _read_name(client, kind, identifier)
+        except (CliError, ValueError):
+            pass
+    name = display_name(name)
+    fallback = f"article [{identifier[:8]}]" if kind == "article" and not ctx.obj.get("as_json") else f"{kind} {identifier}"
+    subject = f'"{name}"' if name else fallback
+    if result_subject:
+        ctx.meta["result_subject"] = subject
+    return f"{subject} [{identifier[:8]}]" if name else subject
+
+
+def action_sentence(action: str) -> Callable[[click.Context, Any], str]:
+    """A contextual renderer for a named action, without decorating its JSON data."""
+    def render(ctx: click.Context, _result: Any) -> str:
+        return f"{action}: {ctx.meta['result_subject']}"
+    return render
+
+
+def named_local_result(describe: Callable[[click.Context, Any], str]) -> Callable[[click.Context, Any], str]:
+    """named_result for a view that needs the context, for example to read the company's timezone."""
+    def render(ctx: click.Context, result: Any) -> str:
+        return f"{ctx.meta['result_subject']}\n{describe(ctx, result)}"
+    return render
+
+
+def named_result(describe: Callable[[Any], str]) -> Callable[[click.Context, Any], str]:
+    """Keep a detail view attached to the resource the person selected."""
+    def render(ctx: click.Context, result: Any) -> str:
+        return f"{ctx.meta['result_subject']}\n{describe(result)}"
+    return render

recala_cli/main.py

@@ -0,0 +1,129 @@
+"""The `recala` command tree.
+
+Nouns are groups (`recala company`, `recala topics`); verbs are their commands. The
+root only resolves the API URL and the injectable seams tests replace: the HTTP
+transport, the poll sleep, the browser opener and whether a person is at a terminal.
+"""
+
+from __future__ import annotations
+
+import difflib
+import os
+import time
+import webbrowser
+
+import click
+
+from recala_cli import __version__, config
+from recala_cli.commands.article import article
+from recala_cli.commands.auth import grant, login, logout, whoami
+from recala_cli.commands.billing import billing
+from recala_cli.commands.bing import bing
+from recala_cli.commands.cadence import autoapprove, cadence, plan
+from recala_cli.commands.connect import cms, connect
+from recala_cli.commands.credits import credits
+from recala_cli.commands.gsc import gsc
+from recala_cli.commands.index import index
+from recala_cli.commands.keys import keys
+from recala_cli.commands.languages import languages
+from recala_cli.commands.knowledge import knowledge
+from recala_cli.commands.monthly_report import monthly
+from recala_cli.commands.notifications import notifications
+from recala_cli.commands.onboard import onboard
+from recala_cli.commands.org import org
+from recala_cli.commands.profile import profile
+from recala_cli.commands.questions import questions
+from recala_cli.commands.refresh import refresh
+from recala_cli.commands.reads import authors, calendar, report
+from recala_cli.commands.slot_topic import replace_slot, waiting_slots
+from recala_cli.commands.schema import schema
+from recala_cli.commands.shell import completion, update
+from recala_cli.commands.skills import skills
+from recala_cli.commands.status import status
+from recala_cli.commands.topics import topics
+from recala_cli.runtime import interactive_human_output
+
+
+class RecalaGroup(click.Group):
+    """Lists each group once: the aliases `org` (of company) and `author` (of authors) work but stay out of --help."""
+
+    UNLISTED_ALIASES = frozenset({"org", "author"})
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        return [name for name in super().list_commands(ctx) if name not in self.UNLISTED_ALIASES]
+
+
+@click.group(cls=RecalaGroup, invoke_without_command=True, context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="recala")
+@click.option(
+    "--api-url", default=None,
+    help="API base URL (else RECALA_API_URL, else the config file, else production).",
+)
+@click.option(
+    "--org", "org_flag", default=None,
+    help="Company name, slug or id for this command (the same as --org after the command; that one wins).",
+)
+@click.pass_context
+def cli(ctx: click.Context, api_url: str | None, org_flag: str | None) -> None:
+    """Drive a Recala company from the terminal, by hand or through an AI agent.
+    Start with: recala onboard
+    """
+    seams = ctx.ensure_object(dict)
+    seams.setdefault("transport", None)
+    seams.setdefault("sleep", time.sleep)
+    seams.setdefault("clock", time.time)
+    seams.setdefault("open_browser", webbrowser.open)
+    # None: decided from the terminal (confirm.is_interactive).
+    seams.setdefault("interactive", None)
+    seams["api_url"] = config.api_url(api_url)
+    seams["org_flag"] = org_flag
+    if ctx.invoked_subcommand is None:
+        if (not interactive_human_output(ctx) or
+                os.environ.get("RECALA_JSON", "").lower() not in ("", "0", "false", "no", "off")):
+            raise click.exceptions.NoArgsIsHelpError(ctx)
+        click.echo("Recala helps your company compete for answers "
+                   "with articles signed by a named person.\n\n"
+                   "1. Sign in: recala login\n"
+                   "2. Choose your company: recala company use <name>\n"
+                   "3. Preview your plan: recala plan\n\n"
+                   "Everything: recala --help")
+
+
+COMMANDS = (completion, update, onboard, status, login, logout, whoami, grant, org, authors, cms, connect, bing, gsc, knowledge,
+            credits, billing, topics, questions, keys, article, index, calendar, report, schema, skills,
+            cadence, autoapprove, plan, notifications, refresh)
+for command in COMMANDS:
+    cli.add_command(command)
+topics.add_command(waiting_slots)
+topics.add_command(replace_slot)
+cli.add_command(org, name="company")
+cli.add_command(authors, name="author")
+org.add_command(languages)
+org.add_command(profile)
+report.add_command(monthly)
+
+
+def suggest_when_unknown(group: click.Group, seen: set[int] | None = None) -> None:
+    """An unknown command names the closest real one, in the root and in every group below it."""
+    seen = set() if seen is None else seen
+    if id(group) in seen:
+        return
+    seen.add(id(group))
+    resolve = group.resolve_command
+
+    def resolve_or_suggest(ctx: click.Context, args: list[str]):
+        name = args[0] if args else ""
+        if name and not name.startswith("-") and group.get_command(ctx, name) is None:
+            close = difflib.get_close_matches(name, group.list_commands(ctx), n=1, cutoff=0.6)
+            path = " ".join(["recala", *ctx.command_path.split()[1:]])
+            ctx.fail(f"No such command {name!r}. "
+                     + (f"Did you mean {close[0]!r}?" if close else f"Run `{path} --help` to see every command."))
+        return resolve(ctx, args)
+
+    group.resolve_command = resolve_or_suggest  # type: ignore[method-assign]
+    for command in group.commands.values():
+        if isinstance(command, click.Group):
+            suggest_when_unknown(command, seen)
+
+
+suggest_when_unknown(cli)