hap-cli 0.8.22__tar.gz → 0.8.23__tar.gz

{hap_cli-0.8.22 → hap_cli-0.8.23}/MANIFEST.in

@@ -11,8 +11,5 @@ include sources/v3-api-schema/INDEX.json
 include hap_cli/README.md
 include hap_cli/README_CN.md
 recursive-include hap_cli/locale *.json
-
-# edit-spec schemas are canonical in the hap-cli-app-editor skill; ship them
-# in the sdist so setup.py's build step can mirror them into
-# hap_cli/core/editor/editspec/ for the ``hap app-editor`` runtime loader.
-recursive-include skills/cli/hap-cli-app-editor/scripts/editspec *.json
+include hap_cli/guide/index.json
+recursive-include hap_cli/guide *.md

{hap_cli-0.8.22 → hap_cli-0.8.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hap-cli
-Version: 0.8.22
+Version: 0.8.23
 Summary: CLI harness for Mingdao HAP - Enterprise no-code platform
 Author: hap-cli
 License: Apache-2.0
@@ -306,6 +306,12 @@ discover every subcommand.
 
 > ADDRESS is the file's link — one that has already stopped working is fine, paste it as-is — or just the path part of it. The file itself does not expire, only the link does, so a dead link can always be revived.
 
+### guide — built-in usage guide
+
+| Command | Description |
+|---|---|
+| `guide` | Built-in usage guide: what this version can do, and the value formats that are easy to get wrong (`hap guide <topic>` for detail) |
+
 ### upload — file upload
 
 | Command | Description |

{hap_cli-0.8.22/hap_cli → hap_cli-0.8.23}/README.md

@@ -277,6 +277,12 @@ discover every subcommand.
 
 > ADDRESS is the file's link — one that has already stopped working is fine, paste it as-is — or just the path part of it. The file itself does not expire, only the link does, so a dead link can always be revived.
 
+### guide — built-in usage guide
+
+| Command | Description |
+|---|---|
+| `guide` | Built-in usage guide: what this version can do, and the value formats that are easy to get wrong (`hap guide <topic>` for detail) |
+
 ### upload — file upload
 
 | Command | Description |

{hap_cli-0.8.22 → hap_cli-0.8.23/hap_cli}/README.md

@@ -277,6 +277,12 @@ discover every subcommand.
 
 > ADDRESS is the file's link — one that has already stopped working is fine, paste it as-is — or just the path part of it. The file itself does not expire, only the link does, so a dead link can always be revived.
 
+### guide — built-in usage guide
+
+| Command | Description |
+|---|---|
+| `guide` | Built-in usage guide: what this version can do, and the value formats that are easy to get wrong (`hap guide <topic>` for detail) |
+
 ### upload — file upload
 
 | Command | Description |

{hap_cli-0.8.22 → hap_cli-0.8.23}/hap_cli/README_CN.md

@@ -251,6 +251,12 @@ hap --json worksheet record list WORKSHEET_ID
 
 > ADDRESS 传文件的链接即可——**已经失效的链接照样能传，原样粘贴**——也可以只传路径部分。文件本身不会过期，过期的只是链接，所以失效链接随时可以重新生成。
 
+### guide — 内置使用指南
+
+| 命令 | 说明 |
+|---|---|
+| `guide` | 内置使用指南：当前版本能做什么、哪些取值格式容易写错（`hap guide <主题>` 看细节） |
+
 ### upload — 文件上传
 
 | 命令 | 说明 |

{hap_cli-0.8.22 → hap_cli-0.8.23}/hap_cli/__init__.py

@@ -1,3 +1,3 @@
 """CLI harness for Mingdao HAP (hap-cli)."""
 
-__version__ = "0.8.22"
+__version__ = "0.8.23"

{hap_cli-0.8.22 → hap_cli-0.8.23}/hap_cli/commands/auth_cmd.py

@@ -30,7 +30,11 @@ SERVER_HELP = (
 )
 
 
-@click.group(help=t('Manage authentication and session identity.'))
+@click.group(help=t(
+    'Manage authentication and session identity.\n\n'
+    'Signing in, keeping several environments and accounts, and choosing the '
+    'current organization are walked through in `hap guide setup`.'
+))
 def auth():
     pass
 

{hap_cli-0.8.22 → hap_cli-0.8.23}/hap_cli/commands/chat_cmd.py

@@ -73,7 +73,11 @@ def _output_chat_list_table(rows):
     )
 
 
-@click.group(help=t('Chat and messaging management.'))
+@click.group(help=t(
+    'Chat and messaging management.\n\n'
+    'To follow a notification back to the app record it belongs to, see '
+    '`hap guide messages`.'
+))
 def chat():
     pass
 

hap_cli-0.8.23/hap_cli/commands/guide_cmd.py

@@ -0,0 +1,36 @@
+"""CLI command for the built-in usage guide."""
+
+import click
+
+from hap_cli.context import pass_context
+from hap_cli.core import guide as guide_mod
+from hap_cli.i18n import t
+
+
+@click.command("guide")
+@click.argument("topic", required=False)
+@pass_context
+def guide(ctx, topic):
+    """How to use this tool: what it can do, and how to get the values right.
+
+    \b
+      hap guide            what hap can do, and which topics go deeper
+      hap guide record     writing records: what value each field type wants
+
+    Run this before composing commands — it describes the version of hap
+    installed on this machine, so it never disagrees with what you get.
+    """
+    try:
+        from hap_cli.hap_cli import cli as root
+
+        if topic:
+            body = guide_mod.render_topic(topic)
+            ctx.output({"topic": topic, "text": body},
+                       lambda d: click.echo(d["text"]))
+            return
+        payload = guide_mod.overview_payload(root)
+        ctx.output(payload, lambda d: click.echo(d["text"]))
+    except guide_mod.UnknownTopic as e:
+        ctx.handle_error(e)
+    except Exception as e:
+        ctx.handle_error(e)

{hap_cli-0.8.22 → hap_cli-0.8.23}/hap_cli/commands/record_cmd.py

@@ -90,6 +90,10 @@ def record_create(ctx, worksheet_id, field, fields_json, no_workflow):
 
     Pass values either as repeated -f CONTROL_ID=VALUE pairs or as one
     --fields-json array.
+
+    What to put in a value depends on the field type, and a wrong shape is
+    usually accepted and stored broken rather than rejected — see
+    `hap guide record` before writing, and read the record back after.
     """
     if field and fields_json:
         raise click.UsageError("Pass exactly one of -f or --fields-json.")
@@ -162,6 +166,10 @@ def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow):
     fields change), a child row without a "rowid" adds a new row, and a
     child row with "_delete": true removes that row. Rows you don't list
     are left untouched. An empty list (or null) clears the sub-table.
+
+    Every other field type replaces rather than merges: passing a new value
+    for a multi-select, attachment or relation field drops whatever was
+    there. Value formats per field type are in `hap guide record`.
     """
     if field and fields_json:
         raise click.UsageError("Pass exactly one of -f or --fields-json.")

{hap_cli-0.8.22 → hap_cli-0.8.23}/hap_cli/commands/worksheet_cmd.py

@@ -11,7 +11,12 @@ from hap_cli.utils.options import org_id_option, require_api_project_id
 from hap_cli.i18n import t
 
 
-@click.group(help=t('Worksheet operations.'))
+@click.group(help=t(
+    'Worksheet operations.\n\n'
+    'Writing records: the value each field type expects (options, members, '
+    'relations, sub-tables, attachments) is covered by `hap guide record` — '
+    'a wrong shape is usually accepted and stored broken.'
+))
 def worksheet():
     pass
 

{hap_cli-0.8.22 → hap_cli-0.8.23}/hap_cli/core/editor/editspec.py

@@ -6,11 +6,10 @@ only the one module schema named by the op.type prefix is loaded and used
 for deep validation (dispatched to the matching verb branch for precise
 errors).
 
-Schemas are canonical in the skill
-(``skills/cli/hap-cli-app-editor/scripts/editspec/``). :func:`schema_dir`
-resolves them for both the editable/repo layout and a pip-installed wheel
-(where ``setup.py`` mirrors them into ``hap_cli/core/editor/editspec/``,
-the same trick used for the V3 schemas).
+Schemas are canonical in this package (``hap_cli/core/editor/editspec/``)
+and ship with it, so they resolve identically in a checkout and in an
+installed wheel — see :func:`schema_dir` for why they no longer live in
+the hap-cli-app-editor skill.
 """
 from __future__ import annotations
 
@@ -74,30 +73,26 @@ RETIRED_OPS = {
     "section.delete": "hap app delete-section",
 }
 
-_SKILL_REL = ("skills", "cli", "hap-cli-app-editor", "scripts", "editspec")
-
-
 @lru_cache(maxsize=1)
 def schema_dir() -> Path:
     """Locate the edit-spec schema directory.
 
-    Resolution order:
-      1. Wheel-bundled copy next to this module (``editspec/``), created
-         by setup.py's build step for installed packages.
-      2. Repo/editable layout: ``<repo>/skills/cli/hap-cli-app-editor/
-         scripts/editspec`` found by walking up from this file.
+    The schemas live next to this module and are tracked with the package,
+    so this resolves identically in a checkout and in an installed wheel.
+
+    They used to be canonical in the hap-cli-app-editor skill, mirrored in
+    at build time by setup.py. That broke when the skills moved to their
+    own repository and were linked back in: the build step found nothing
+    on a machine without that checkout, skipped silently, and shipped a
+    wheel whose ``hap app-editor`` could not load a single schema. A build
+    input has to be inside the repository that builds it.
     """
     bundled = Path(__file__).resolve().parent / "editspec"
     if bundled.is_dir() and any(bundled.glob("*.schema.json")):
         return bundled
-    here = Path(__file__).resolve()
-    for parent in here.parents:
-        cand = parent.joinpath(*_SKILL_REL)
-        if cand.is_dir():
-            return cand
     raise EditSpecError([
-        "could not locate edit-spec schemas (neither the bundled copy nor "
-        "skills/cli/hap-cli-app-editor/scripts/editspec)"])
+        "could not locate the edit-spec schemas that ship with this "
+        "package (hap_cli/core/editor/editspec/)"])
 
 
 def _load_schema(filename: str) -> dict[str, Any]:

hap_cli-0.8.23/hap_cli/core/guide.py

@@ -0,0 +1,176 @@
+"""Usage guidance that ships with — and updates with — the CLI.
+
+The hap-cli skill used to carry the command map as a static file on the
+user's machine, frozen at install time. Guidance lives here instead, for
+one reason: this package auto-updates, so whatever it says matches the
+`hap` the caller is actually running. The skill shrinks to a stub that
+says "run `hap guide`".
+
+Two halves:
+
+- **Generated** — the command map is walked off the live Click tree
+  (``command_map``). It cannot name a command that does not exist, and
+  it cannot omit one that does. Nothing about it is written down.
+- **Written** — prose that the tree cannot express (how to log in, what
+  value shape each field type wants, which specialised skill to hand off
+  to) lives in ``hap_cli/guide/<lang>/<topic>.md``, declared in
+  ``index.json``.
+
+The bare overview enumerates its own topics so the skill stub never has
+to name them; naming them there is exactly the detail that goes stale.
+"""
+from __future__ import annotations
+
+import json
+import textwrap
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Optional
+
+import click
+
+GUIDE_DIR = Path(__file__).resolve().parent.parent / "guide"
+BASE_LANG = "en"
+
+# Two spaces of hanging indent under each group name, wide enough for the
+# longest top-level group without the help column drifting.
+_NAME_COL = 14
+
+# Wrap the subcommand row so a wide group (worksheet has 27) stays
+# readable in a normal terminal instead of running off the edge.
+_WRAP_COL = 88
+
+
+class UnknownTopic(Exception):
+    """Raised for a topic name the guide does not ship."""
+
+
+@lru_cache(maxsize=1)
+def _index() -> list[dict[str, Any]]:
+    with open(GUIDE_DIR / "index.json", encoding="utf-8") as fh:
+        return json.load(fh)["topics"]
+
+
+def _resolve_lang(lang: Optional[str]) -> str:
+    if lang is None:
+        from hap_cli.i18n import get_active_language
+
+        lang = get_active_language()
+    return lang
+
+
+def _pick(entry: dict[str, Any], lang: str) -> str:
+    """Localized string with the English base as fallback."""
+    return entry.get(lang) or entry[BASE_LANG]
+
+
+def available_topics(lang: Optional[str] = None) -> list[dict[str, str]]:
+    """Declared topics in display order: ``{name, title, summary}``."""
+    lang = _resolve_lang(lang)
+    return [
+        {
+            "name": t["name"],
+            "title": _pick(t["title"], lang),
+            "summary": _pick(t["summary"], lang),
+        }
+        for t in _index()
+    ]
+
+
+def render_topic(name: str, lang: Optional[str] = None) -> str:
+    """Body of one topic, falling back to English when the active
+    language has no copy of it."""
+    known = [t["name"] for t in _index()]
+    if name not in known:
+        raise UnknownTopic(
+            f"No guide topic named '{name}'. Available topics: "
+            + ", ".join(known)
+        )
+    lang = _resolve_lang(lang)
+    for candidate in (lang, BASE_LANG):
+        path = GUIDE_DIR / candidate / f"{name}.md"
+        if path.exists():
+            return path.read_text(encoding="utf-8").strip()
+    raise UnknownTopic(f"Guide topic '{name}' has no content installed.")
+
+
+def command_map(root: click.Group) -> str:
+    """Render the live command tree: every group, and the commands under it.
+
+    Generated rather than written so it always describes the installed
+    version. Hidden commands are omitted — they are not part of the
+    surface a caller should be pointed at.
+    """
+    lines: list[str] = []
+    for name, cmd in sorted(root.commands.items()):
+        if cmd.hidden:
+            continue
+        summary = (cmd.get_short_help_str(limit=60) or "").strip()
+        lines.append(f"  {name:<{_NAME_COL}}{summary}")
+        children = _child_names(cmd)
+        if children:
+            indent = " " * (2 + _NAME_COL)
+            lines.extend(textwrap.wrap(
+                " ".join(children), width=_WRAP_COL,
+                initial_indent=indent, subsequent_indent=indent,
+                break_long_words=False, break_on_hyphens=False,
+            ))
+    return "\n".join(lines)
+
+
+def _child_names(cmd: click.Command) -> list[str]:
+    """Direct subcommand names of a group, one nesting level only.
+
+    Deeper levels (``worksheet record create``) are reachable through
+    ``--help`` and would drown the map; the point here is to show that
+    the capability exists, not to restate every signature.
+    """
+    if not isinstance(cmd, click.Group):
+        return []
+    return sorted(n for n, c in cmd.commands.items() if not c.hidden)
+
+
+def _topic_lines(lang: str) -> str:
+    rows = available_topics(lang)
+    width = max(len(t["name"]) for t in rows) + len("hap guide ") + 2
+    return "\n".join(
+        f"  {('hap guide ' + t['name']):<{width}}{t['summary']}" for t in rows
+    )
+
+
+def render_overview(root: click.Group, lang: Optional[str] = None) -> str:
+    """The bare ``hap guide``: how to work, what exists, where to go next."""
+    lang = _resolve_lang(lang)
+    for candidate in (lang, BASE_LANG):
+        path = GUIDE_DIR / candidate / "overview.md"
+        if path.exists():
+            template = path.read_text(encoding="utf-8")
+            break
+    else:  # pragma: no cover - shipped content is validated by tests
+        raise UnknownTopic("The guide overview has no content installed.")
+    from hap_cli import __version__
+
+    return (
+        template.replace("{version}", __version__)
+        .replace("{command_map}", command_map(root))
+        .replace("{topics}", _topic_lines(lang))
+        .strip()
+    )
+
+
+def overview_payload(root: click.Group, lang: Optional[str] = None) -> dict[str, Any]:
+    """Machine-readable form of the overview for ``--json`` callers."""
+    lang = _resolve_lang(lang)
+    return {
+        "text": render_overview(root, lang),
+        "topics": available_topics(lang),
+        "commands": [
+            {
+                "name": name,
+                "summary": (cmd.get_short_help_str(limit=60) or "").strip(),
+                "subcommands": _child_names(cmd),
+            }
+            for name, cmd in sorted(root.commands.items())
+            if not cmd.hidden
+        ],
+    }

hap_cli-0.8.23/hap_cli/guide/en/messages.md

@@ -0,0 +1,54 @@
+# From a message or notification to its record
+
+A lot of unread traffic is "someone commented on a record" or "a workflow copied you on
+a record". To follow it back to the record, use this fixed path — **do not go hunting
+through worksheets**.
+
+## Three steps
+
+**1. See which category the conversation belongs to**
+
+```bash
+hap --json chat list
+```
+
+Every conversation carries a `category`: `system` / `post` / `calendar` / `task` / `kc` /
+`hr` / `app` / `workflow`, plus `user` for one-to-one and `group` for group chats.
+
+- **Record discussions inside an app or worksheet are `app`**
+- Workflow notifications are `workflow`
+
+**2. Pull the detail for that category**
+
+```bash
+hap --json chat messages --category app        # or workflow, etc.
+```
+
+- Record-discussion entries carry **`appId` + `worksheetId` + `rowId`** directly, along
+  with `viewId`, `comment.recordName` and `comment.entityName`.
+- Workflow **cc / participant** notifications have the `appId` / `worksheetId` / `rowId`
+  resolved out of the record link for you.
+- One-to-one and group chats do not use `--category`; use `--with-user <accountId>` or
+  `--group-id <groupId>` (the id is the conversation's `value`).
+
+**3. Read the record and its discussion**
+
+```bash
+hap worksheet record get <worksheetId> <rowId> -a <appId>
+hap worksheet record discussions <worksheetId> <rowId> -a <appId>
+```
+
+## The one thing to get right
+
+> Use the `appId` **on the message entry** (resolved from the discussion's `extendsId`
+> or the record link) — **not the one on the conversation itself**. The conversation's
+> appId belongs to the message centre and is frequently a deleted app; querying a record
+> with it reports that the application has been deleted.
+
+## Working backwards from a URL
+
+A worksheet view page: `/app/<appId>/<sectionId>/<worksheetId>/<viewId>`
+A record page: `/app/<appId>/<worksheetId>/<viewId>/row/<rowid>`
+
+With worksheetId + rowid you can go straight to `record get` / `record update`;
+`sectionId` and `viewId` are not needed to change data.

hap_cli-0.8.23/hap_cli/guide/en/overview.md

@@ -0,0 +1,45 @@
+# Using hap (hap-cli {version})
+
+`hap` wraps the HAP enterprise platform as a command line. Sign in once and you can
+look people up, send messages, post updates, manage calendars, read and write
+worksheet records, handle approvals, and build or edit applications.
+
+## How to work with it
+
+1. **Check the environment is ready** — installed, signed in, current organization
+   chosen (and a default app if you will touch records). `hap auth whoami` confirms it;
+   `hap guide setup` covers the rest.
+2. **Decide what kind of task this is**
+   - A single operation (find a person, send a message, read or write one record,
+     act on one approval) → use the matching top-level command below.
+   - Building a whole app, restructuring one, or complex filtering and pivots
+     → hand off to a specialised skill, see `hap guide skills`.
+3. **Read the options before composing** — `hap <command> --help` is the only
+   authority on arguments. **Do not compose commands from memory**: this tool
+   updates itself, so the version you remember may not be the one installed.
+   Add `--json` for structured output in scripts.
+
+## Command map
+
+This is the complete top-level surface of **the version installed on this machine**,
+generated live rather than copied. Expand any of them with `hap <command> --help`.
+
+{command_map}
+
+## Topics
+
+{topics}
+
+## The traps people hit most
+
+- `--json` and `--profile` are **global options and go between `hap` and the
+  subcommand**: `hap --json chat list` ✅, `hap chat list --json` ❌ ("No such option").
+- To see a worksheet's fields use `hap worksheet fields WS_ID` — not get / structure.
+- `record create/update/delete` **do not accept `--app-id`**; they use the default app.
+  Set it once with `hap app select <appId>` before writing.
+- Field value shapes differ a lot and **a wrong one still reports success** —
+  read `hap guide record` before writing.
+- Before touching workflow nodes run `hap workflow structure PROCESS_ID` and use the
+  real ids; do not invent node ids.
+- To debug, turn on logging: `hap config log on` (written to `~/.hap-cli/hap-cli.log`,
+  with credentials redacted).