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

{hap_cli-0.8.22 → hap_cli-0.8.24}/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.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hap-cli
-Version: 0.8.22
+Version: 0.8.24
 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.24}/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.24/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.24}/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.24}/hap_cli/__init__.py

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

{hap_cli-0.8.22 → hap_cli-0.8.24}/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.24}/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.24/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.24}/hap_cli/commands/record_cmd.py

@@ -84,12 +84,20 @@ def record_get(ctx, worksheet_id, row_id, view_id):
                    "list of option names or keys; member/relation fields a "
                    "list of ids). Use either this or -f, not both.")
 @click.option("--no-workflow", is_flag=True, help="Don't trigger workflows")
+@click.option(
+    "--app-id", "-a", default="",
+    help="Application ID. Optional — the worksheet id is enough on its own; this only scopes the field lookup.",
+)
 @pass_context
-def record_create(ctx, worksheet_id, field, fields_json, no_workflow):
+def record_create(ctx, worksheet_id, field, fields_json, no_workflow, app_id):
     """Create a new record.
 
     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.")
@@ -108,10 +116,11 @@ def record_create(ctx, worksheet_id, field, fields_json, no_workflow):
                 raise click.UsageError(str(exc))
         else:
             raw = _parse_fields(field)
-        controls = rec_mod.encode_controls_by_id(session, worksheet_id, raw)
+        controls = rec_mod.encode_controls_by_id(
+            session, worksheet_id, raw, app_id=app_id)
         data = rec_mod.create_record(
             session, worksheet_id, controls,
-            trigger_workflow=not no_workflow,
+            trigger_workflow=not no_workflow, app_id=app_id,
         )
         ctx.output(data, lambda d: click.echo(f"Created: {d}"))
     except Exception as e:
@@ -149,8 +158,12 @@ def _fields_json_to_raw(fields_json):
                    "list of option names or keys; member/relation fields a "
                    "list of ids). Use either this or -f, not both.")
 @click.option("--no-workflow", is_flag=True, help="Don't trigger workflows")
+@click.option(
+    "--app-id", "-a", default="",
+    help="Application ID. Optional — the worksheet id is enough on its own; this only scopes the field lookup.",
+)
 @pass_context
-def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow):
+def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow, app_id):
     """Update a record.
 
     Pass values either as repeated -f CONTROL_ID=VALUE pairs or as one
@@ -162,6 +175,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.")
@@ -172,10 +189,10 @@ def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow):
         else:
             raw = _parse_fields(field)
         controls = rec_mod.encode_controls_by_id(
-            session, worksheet_id, raw, for_update=True)
+            session, worksheet_id, raw, for_update=True, app_id=app_id)
         data = rec_mod.update_record(
             session, worksheet_id, row_id, controls,
-            trigger_workflow=not no_workflow,
+            trigger_workflow=not no_workflow, app_id=app_id,
         )
         ctx.output(data, lambda d: click.echo(f"Updated: {d}"))
     except Exception as e:

{hap_cli-0.8.22 → hap_cli-0.8.24}/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.24}/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.24/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
+        ],
+    }